Classify Text
The classify() method sends text to the AI Guard service for classification. It returns match results with position offsets, confidence scores, and classifier identifiers for any detected sensitive data.
Basic Classification
from ai_guard import AIGuardClient
from ai_guard.api import (
AIPlatform,
ClassificationRequest,
ClassifierDescriptionDefault,
)
client = AIGuardClient(
"https://ai-guard.example.com:4443",
token="your-api-key",
agent_id="my-agent",
platform=AIPlatform.AMAZON_BEDROCK,
)
request = ClassificationRequest(
context={"actor": "user"},
classifier_description=ClassifierDescriptionDefault(),
text="phone 321-507-0525 number",
)
response = client.classify(request)
for match in response.matches:
print(f"{match.classifier}: '{match.text}' at [{match.start}:{match.end}] (confidence: {match.confidence})")
# US_PHONE_NUMBER: '321-507-0525' at [6:18] (confidence: 100)Classification Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
context | dict | Yes | Must include "actor" set to "user" or "agent" to identify the source of the text |
classifier_description | ClassifierDescription | Yes | Specifies which classifiers to use. See Classifier Descriptions |
text | str | Yes | The text to classify |
The context Parameter
context ParameterThe context dictionary is passed through to metrics and must include:
| Key | Values | Description |
|---|---|---|
actor | "user" or "agent" | Identifies whether the text is a user prompt or an agent response |
Automatic Context InjectionThe
agent_idandplatformfields are automatically injected by the client. You only need to specifyactorin your context.
Classification Response
The response contains a list of matches, each representing a detected sensitive data pattern:
| Field | Type | Description |
|---|---|---|
classifier | str | The name of the matched classifier (e.g., US_PHONE_NUMBER) |
text | str | The matched text content |
start | int | Starting character position of the match |
end | int | Ending character position of the match |
confidence | int | Confidence score (0–100) |
Example Response
response = client.classify(request)
# Access match details
for match in response.matches:
print(f"Classifier: {match.classifier}")
print(f"Text: {match.text}")
print(f"Position: [{match.start}:{match.end}]")
print(f"Confidence: {match.confidence}")
print("---")Classifying User Prompts vs. Agent Responses
Use the actor field in context to differentiate between user input and AI-generated output:
# Classify a user prompt
user_request = ClassificationRequest(
context={"actor": "user"},
classifier_description=ClassifierDescriptionDefault(),
text=user_input,
)
user_result = client.classify(user_request)
# Classify an agent response
agent_request = ClassificationRequest(
context={"actor": "agent"},
classifier_description=ClassifierDescriptionDefault(),
text=agent_output,
)
agent_result = client.classify(agent_request)Using a Specific Classification Profile
Instead of the default profile, specify a profile by UUID:
from ai_guard.api import ClassifierDescriptionProfile
request = ClassificationRequest(
context={"actor": "user"},
classifier_description=ClassifierDescriptionProfile(
uuid="7dbf380f-0af8-4276-acb0-85413db2dbff",
version=1,
),
text="My SSN is 123-45-6789",
)
response = client.classify(request)See Classifier Descriptions for all available options.
Handling Empty Results
If no sensitive data is detected, response.matches will be an empty list:
response = client.classify(request)
if not response.matches:
print("No sensitive data detected")
else:
print(f"Found {len(response.matches)} matches")Error Handling
The classify() method raises specific exceptions based on the HTTP response:
| HTTP Status | Exception | Description |
|---|---|---|
| 400 | ValueError | Invalid request (e.g., malformed classifier description) |
| 401 | PermissionError | Invalid or missing API key |
| 500+ | RuntimeError | Server error |
| Other | RuntimeError | Unexpected error |
try:
response = client.classify(request)
except ValueError as e:
print(f"Bad request: {e}")
except PermissionError as e:
print(f"Authentication failed: {e}")
except RuntimeError as e:
print(f"Service error: {e}")What's Next?
- Redact Sensitive Data — Mask or block detected sensitive data
- Streaming Classification — Classify streaming LLM responses in real time
- Classifier Descriptions — Explore all classifier selection options
Updated 3 days ago