AI Provider TypeSafe AI

TypeSafe AI Provider connects the Drupal AI module to TypeSafe AI System One models, starting with Jev.

Give Jev state (text or structured data) and a set of typed questions, and it returns answers with probabilities. Your application controls the workflow and thresholds. Use it for routing, classification, scoring, verification and moderation.

Supported operations

• Decision: Ask true/false, choice and score questions through the Decision operation in the AI module (AI 1.6 and later).
• Text classification: The labels you supply become a choice question, and each label's probability becomes its confidence score in Drupal AI's standard text classification response.
• Moderation: Each configured policy category becomes a true/false question. Content is flagged when a probability exceeds your configured threshold; a tie at exactly the threshold, such as a rounded 0.50, does not flag. Jev can also check other providers' chat requests through the AI module's external moderation settings.

The provider includes automatic model discovery, retries with backoff, and error handling through the AI module's exception types. It declares what each model supports, including Jev's limits of 255 choice options and 10 score levels, and checks every request locally, so an invalid request never reaches the API or paid guardrails. API credentials are managed through Drupal's Key module.

Decision question types

• True/false (noul): Whether a statement holds. Returns the probability that it is true.
• Choice: Which of a defined set of options fits. Returns the chosen option, a probability per option and a confidence value.
• Score: Where something sits on an ordered scale. Returns a probability-weighted level, a probability per level and a confidence value.

Ask multiple independent questions about the same state in one request. TypeSafe answers them in parallel. Jev is text-only, so a Decision request with image files is rejected before any API call.

Explorer, field automation and guardrails

These integrations are part of the AI module since 1.6 and work with any provider implementing its Decision operation:

• Decision Explorer (AI API Explorer): Try state and questions in the browser, see the selected model's declared features and limits, inspect probabilities and copy the equivalent PHP.
• Decision automator rules (AI Automators): Populate Boolean, list and numeric fields using typed questions. Supports single-choice and multi-select lists. Optional thresholds leave a field unchanged when the model is unsure: a minimum confidence for lists and numeric fields, and separate true and false thresholds for Boolean fields.
• Decision guardrails: Apply regular-expression, character-length and moderation checks to Decision requests. Moderation covers both the state and the question text. No guardrails are enabled automatically.

The AI module's existing text classification and moderation explorers also support this provider.

Example

use Drupal\ai\OperationType\Decision\DecisionInput;
use Drupal\ai\OperationType\Decision\Value\ChoiceQuestion;
use Drupal\ai\OperationType\Decision\Value\NoulQuestion;
use Drupal\ai\OperationType\Decision\Value\ScoreQuestion;

$provider = \Drupal::service('ai.provider')->createInstance('typesafeai');

$input = new DecisionInput(
  ['ticket' => ['message' => 'I was charged twice. Please refund the duplicate.']],
  [
    'refund_requested' => new NoulQuestion('Is the customer asking for money back in `ticket.message`?'),
    'team' => new ChoiceQuestion('Which team should handle `ticket`?', [
      'billing' => 'Charges, invoices, refunds or subscriptions',
      'technical' => 'Bugs, errors or integration problems',
      'sales' => 'Pricing, plans or account questions',
    ]),
    'frustration' => new ScoreQuestion('How frustrated does the customer appear in `ticket.message`?', [
      'Calm and matter-of-fact',
      'Frustrated but civil',
      'Very angry or threatening to leave',
    ]),
  ],
);

$response = $provider->decision($input, 'jev-latest', ['my_module'])->getNormalized();
$refund_likely = $response->getNoul('refund_requested')->isLikely(0.7);
$team = $response->getChoice('team');
$needs_review = !$team->isConfident(0.8);
$frustration = $response->getScore('frustration');
$frustration_level = $frustration->isConfident(0.6) ? $frustration->getScore() : NULL;

Thresholds and actions stay in your code. Answers retain their probabilities, so thresholds can change without another request. isLikely() is true only when the probability exceeds the threshold; isConfident() minimums are inclusive. Confidence describes how concentrated the probability distribution is; it does not guarantee correctness. Validate thresholds against examples from your application.

Requirements

• Drupal 10.5+ or Drupal 11.2+.
• AI 1.6.0 or later within the 1.x series, which includes the Decision operation. Until AI 1.6.0 is released, use AI's 1.6.x development branch.
• Key 1.18 or later within the 1.x series, to store the API key.
• A TypeSafe AI account and API key.
• Optional: AI Logging 1.3.2 or later records token usage for all three operations.

Installation and configuration

1. Install with Composer. Until AI 1.6.0 and a release of this project are available, require both development branches: composer require 'drupal/ai:1.6.x-dev@dev' 'drupal/ai_provider_typesafeai:1.1.x-dev@dev'. Once AI 1.6.0 is released, 'drupal/ai:^1.6' is enough for AI.
2. Enable TypeSafe AI Provider (ai_provider_typesafeai). Drupal also enables AI and Key.
3. Create a Key holding your TypeSafe API key at Configuration » System » Keys.
4. Select the key at Configuration » AI » Provider settings » TypeSafe AI. The form validates the key against the API and sets Jev as the default for Decision, Text classification and Moderation where no default exists.
5. Optionally enable AI API Explorer for the Decision Explorer, or AI Automators for the Decision field rules. Install Token if needed before enabling AI Automators.

Branches

• 1.1.x (recommended): Requires AI 1.6, where the Decision operation is part of the AI module. It does not use the separate AI Decision project.
• 1.0.x: Built for the earlier, separate AI Decision project on AI 1.5. New sites should use 1.1.x.

Sites that tested Decision through the AI issue fork for AI merge request !2046 must remove that Composer repository before updating; the README's "Moving off the AI issue fork" section explains how.

Documentation

• The TypeSafe AI Provider README covers configuration, supported operations, model capabilities, model discovery and error handling.
• AI's Decision documentation: calling Decision (including guardrails), the Decision provider contract and the Decision automator rules.
• TypeSafe AI documentation covers question design, confidence and application patterns.

Notes

• Model aliases such as jev-latest can change. Choose an advertised version ID when you need a fixed model version.
• Each moderation category costs one question per call. Configure the categories needed for your application.
• Do not configure the TypeSafe provider to moderate its own requests; the AI module's moderation gate would recurse.
• Only the three text question types are supported. TypeSafe's image-based bounding_box question type is not exposed.

Contact us

Contact Skvare for AI integration with your CMS or CiviCRM systems.