> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```python
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](https://developer.onetrust.com/onetrust/docs/ai-guard-classifier-descriptions) |
| `text`                   | `str`                   | Yes      | The text to classify                                                                                    |

### The `context` Parameter

The `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 Injection
>
> The `agent_id` and `platform` fields are automatically injected by the client. You only need to specify `actor` in 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

```python
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:

```python
# 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:

```python
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](https://developer.onetrust.com/onetrust/docs/ai-guard-classifier-descriptions) for all available options.

## Handling Empty Results

If no sensitive data is detected, `response.matches` will be an empty list:

```python
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                                         |

```python
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](https://developer.onetrust.com/onetrust/docs/ai-guard-redaction) — Mask or block detected sensitive data
* [Streaming Classification](https://developer.onetrust.com/onetrust/docs/ai-guard-streaming) — Classify streaming LLM responses in real time
* [Classifier Descriptions](https://developer.onetrust.com/onetrust/docs/ai-guard-classifier-descriptions) — Explore all classifier selection options