Topic Management

1. Define your topics. Give each topic a name. Add a description to clarify its scope and labeled examples to illustrate text that matches or doesn't match.
2. Submit the text and topic configuration. Include the text in multimodalInput, add guardrailConfigs.topicConfig, and select a supported Guardrails system version.
3. Read the results. Use results.topicModeration.topics to find the result for every configured topic. More than one topic can match the same text.
4. Apply your application's policy. For example, your application can allow the interaction, redirect the user to a supported subject, or prevent the content from being passed to a model or shown to a user.

To evaluate a user input, submit it before sending it to the model. To evaluate a model output, submit that output as the text in a separate ApplyGuardrails request before displaying it.

A topic match identifies the subject of the text. It doesn't mean the text is unsafe, and the result doesn't automatically block an inference request. Your application decides which topics require an action.

Send requests to the existing endpoint:

POST /20231130/actions/applyGuardrails

For request signing and the complete API contract, see ApplyGuardrails.

• Set guardrailVersionConfig.guardrailVersion to 1.2.0 or a later supported version. Topic management requires an explicit version selection. Use ListGuardrailVersions to check the available versions, descriptions, and lifecycle states. See Version Selection Workflow for listing requirements and PATCH version selection. The Guardrails system version is separate from the API version in the endpoint path and the SDK version.
• Include exactly one TEXT item in multimodalInput and put the text to classify in content. The languageCode field is optional. If you provide it, use en or an English regional variant such as en-US.
• Omit input. When topicConfig is supplied, including input results in HTTP 400, even if multimodalInput is also provided.
• Add topicConfig under guardrailConfigs. Supply at least one topic in topicConfig.topics.
• Provide the OCID of your compartment in compartmentId.

Topic management evaluates English text only. If the request also contains images, topic classification ignores them. Image-only requests, multiple text items, and invalid or non-English language codes aren't supported for topic classification. Omitting languageCode is allowed.

You can include content moderation, prompt injection detection, and PII detection configurations in the same request. Adding topic management doesn't change those protections. If you omit topicConfig, existing request behavior is preserved and the response doesn't include results.topicModeration.

Define topics in guardrailConfigs.topicConfig.topics. Optionally add labeled examples in guardrailConfigs.topicConfig.fewShotExamples.

For example, if your topics are Exhibit Loans and After-Hours Access, every example must contain both keys in its classification object, even when only one topic applies.

Duplicate-name validation compares topic names. It doesn't reject topics solely because their meanings overlap. For example, names that differ only in letter case are duplicates, but different names with similar meanings aren't automatically duplicates.

To make your definitions clear:

• Use specific topic names and descriptions. For example, Exhibit Loans is more specific than Exhibitions if you want to detect requests to borrow museum objects for display at another venue.
• Use descriptions to explain the intended scope and distinguish related topics.
• Provide representative examples with consistent labels. Label every topic for every example.
• Test with matching text, nonmatching text, and text that could match more than one topic. Refine descriptions and examples based on the results.

The examples guide classification for the current request. To evaluate a revised definition, send another request with the revised topic configuration.

This example checks a message to a fictional museum assistant for exhibit loans and access outside opening hours. The application can use either match to refer the request to museum staff. Replace <your-compartment-ocid> with your compartment OCID.

{
  "multimodalInput": [
    {
      "type": "TEXT",
      "content": "Could our community center borrow the clock exhibit for a local exhibition and collect it after the museum closes?",
      "languageCode": "en"
    }
  ],
  "guardrailConfigs": {
    "topicConfig": {
      "topics": [
        {
          "name": "Exhibit Loans",
          "description": "Requests to temporarily borrow museum objects for display at another venue."
        },
        {
          "name": "After-Hours Access",
          "description": "Requests to enter museum spaces or collect items outside normal opening hours."
        }
      ],
      "fewShotExamples": [
        {
          "userText": "Can our community center borrow the navigation instruments for a school exhibition?",
          "classification": {
            "Exhibit Loans": "true",
            "After-Hours Access": "false"
          }
        },
        {
          "userText": "May the photography club enter the gallery after closing time?",
          "classification": {
            "Exhibit Loans": "false",
            "After-Hours Access": "true"
          }
        },
        {
          "userText": "Which gallery displays the restored clock?",
          "classification": {
            "Exhibit Loans": "false",
            "After-Hours Access": "false"
          }
        }
      ]
    }
  },
  "guardrailVersionConfig": {
    "guardrailVersion": "1.2.0"
  },
  "compartmentId": "<your-compartment-ocid>"
}

This request enables topic classification only. To evaluate the same text with other protections, add their configuration objects alongside topicConfig. See Using the ApplyGuardrails API.

When topic classification succeeds, results.topicModeration.topics contains one result for every configured topic, in the same order as the request. Topics that don't match are included.

The score is a binary classification result, not a graduated confidence score. The result classifies the overall text and doesn't return matched text, offsets, or lengths.

The following illustrative response shows both topics matching the example message:

{
  "results": {
    "topicModeration": {
      "topics": [
        {
          "name": "Exhibit Loans",
          "score": 1.0,
          "isMatched": "true"
        },
        {
          "name": "After-Hours Access",
          "score": 1.0,
          "isMatched": "true"
        }
      ]
    }
  },
  "guardrailVersion": {
    "version": "1.2.0"
  }
}

Your application can act on either match according to its policy. For a topic that doesn't match, the response still includes its name with score: 0.0 and isMatched: "false".

Check that your request includes a supported Guardrails system version and meets the topic and input requirements. Supplying input, an image-only request, multiple text items, an invalid or non-English language code, or an unsupported guardrail version results in HTTP 400. You can omit languageCode.

If results don't reflect your intended topics, review the topic descriptions and example labels. Test revised definitions with representative application text before using the results to enforce your policy.