Metadata-Version: 2.1
Name: atlas-guardrails
Version: 0.4.0a3
Summary: Atlas Guardrails SDK
Author-Email: cchen_varonis <cchen@varonis.com>
License: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Project-URL: Repository, https://github.com/Varonis-Systems/Atlas-alltrue-llm-observability
Requires-Python: >=3.11
Requires-Dist: atlas-guardrails-core[logfire]==0.4.0a3
Provides-Extra: observers
Requires-Dist: wrapt<2.0.0,>=1.17.3; extra == "observers"
Provides-Extra: openai-observers
Requires-Dist: atlas-guardrails[observers]; extra == "openai-observers"
Requires-Dist: openai>=1.107.0; extra == "openai-observers"
Description-Content-Type: text/markdown

# Atlas Guardrails

Atlas Guardrails provides monitoring, observability, and guardrails for Large Language Model interactions. It allows you to track, modify, and secure your LLM API calls with minimal code changes to your existing applications.

## Table of Contents
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
  - [Guardrails](#guardrails)
  - [Observers](#observers)
  - [Traceability](#traceability)
- [Features](#features)
- [Troubleshooting](#troubleshooting)
- [License](#license)

## Installation

### From PyPI

```shell
# Core SDK
pip install atlas-guardrails

# With the OpenAI client observer
pip install "atlas-guardrails[openai-observers]"

# To try a pre-release (alpha) build from the develop branch
pip install --pre atlas-guardrails
```

`atlas-guardrails` automatically pulls in its companion package `atlas-guardrails-core`
(both share the `atlas_guardrails` import namespace).

### For development (editable mode)

```shell
git clone git@github.com:Varonis-Systems/Atlas-alltrue-llm-observability.git
cd Atlas-alltrue-llm-observability

# Using uv (recommended — installs the workspace + dev dependencies)
uv sync --extra openai-observers

# Or using pip
pip install -e ".[openai-observers]"
```

## Configuration

Atlas SDK can be configured through parameters or environment variables:

| Parameter                     | Environment Variable          | Required | Description                                                                                                                                                                                                                                                                                 |
|-------------------------------|-------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `alltrue_api_url`             | `ALLTRUE_API_URL`             | No | The tenant endpoint to send requests to. Defaults to the standard Atlas API endpoint. This is configurable in case you have a custom tenant or need to use a proxy.                                                                                                                       |
| `alltrue_api_key`             | `ALLTRUE_API_KEY`             | Yes | Your API authentication key created inside the Atlas application. This is used to authenticate your requests to the Atlas API. See [API Keys documentation](https://prod.alltrue-be.com/_docs/docs/platform_services/admin_console#api-keys) for details on creating and managing keys. |
| `alltrue_endpoint_identifier` | `ALLTRUE_ENDPOINT_IDENTIFIER` | Yes | Required identifier of the resource configured in the Atlas application. This is used to match the API call with the specific settings and security rules that should be applied for observability.                                                                                       |
| `logging_level`               | -                             | No | Sets the logging verbosity (e.g., "WARNING", "INFO", "DEBUG"). Defaults to "INFO".                                                                                                                                                                                                       |
| `blocking`                    | -                             | No | Boolean flag indicating whether to block on detected abnormalities (for observers). When set to True, the SDK will prevent non-compliant requests/responses from proceeding. Defaults to False.                                                                                             |
| `fastgate`                    | -                             | No | Dictionary of FastGate control direactives. e.g. Provide `{"no-fastgate": True}` to disable FastGate                                                                                                                                                                                        |
| `conversation`                | -                             | No | Dictionary of conversation control direactives. e.g. Provide `{"thread-control": "corrected"}` to enable correct thread conversation                                                                                                                                                        |
| `_keep_alive`                 | `CONFIG_HTTP_KEEPALIVE`       | No | Boolean flag indicating whether to use keep alive connection for APi calls. Default to True                                                                                                                                                                                                 |
| `_timeout`                    | `CONFIG_HTTP_TIMEOUT`         | No | API request timeout in seconds. Default to 5s                                                                                                                                                                                                                                               |
| `_retries`                    | -                             | No | API request failure retries. Default to 0 (disabled).                                                                                                                                                                                                                                       |
| `_batch_size`                 | -                             | No | Integer value indicating the maximun number a batch should be proceeded. Given zero (the default) to disable batch mode.                                                                                                                                                                    |
| `_queue_time`                 | -                             | No | Float value indicating the maximum queuing time a batch should be proceeded. Given zero (the default) to disable batch mode.                                                                                                                                                                |

## Usage

### Guardrails

Guardrails provide validation and filtering for LLM inputs and outputs. They can be used in two modes:

#### 1. Active Guardrails - Validating Messages

```python
from atlas_guardrails.guardrails.chat import ChatGuardrails, GuardrailsException
import httpx
import sys

# Initialize guardrails
guardrails = ChatGuardrails(
    alltrue_api_key="<API_KEY>",
    alltrue_endpoint_identifier="<IDENTIFIER>",
    logging_level="WARNING",
)

messages = ["What day is today?"]

# Validate input messages before sending to LLM
try:
    guarded_input = await guardrails.guard_input(
        prompt_messages=messages,
        fastgate={"no-fastgate": True},                # disable fast gate
        conversation={"thread-control": "corrected"}, # enable correct thread
    )
except GuardrailsException:
    print("Input validation failed - potential policy violation")
    sys.exit(1)

# Use the validated messages with OpenAI API
api_response = await httpx.AsyncClient(
    base_url=f"https://api.openai.com/v1",
).post(
    url=f"/chat/completions",
    json={
        "model": "gpt-4o",
        "messages": [
            {
                "role": "user",
                "content": msg,
            }
            for msg in guarded_input
        ],
    },
)

# Extract model responses
responses = [
    c.get("message", {}).get("content", "")
    for c in api_response.json().get("choices", [])
]

# Validate model outputs
try:
    guarded_output = await guardrails.guard_output(messages, responses)
    # Use guarded_output in your application
except GuardrailsException:
    print("Output validation failed - potential unsafe content")
    sys.exit(1)
```

#### 2. Passive Observation - Monitoring Without Validation

```python
from atlas_guardrails.guardrails.chat import ChatGuardrails, GuardableMessage
import httpx

# Initialize guardrails
guardrails = ChatGuardrails(
    alltrue_api_key="<API_KEY>",
    alltrue_endpoint_identifier="<IDENTIFIER>",
    logging_level="WARNING",
    _batch_size=5, # provide a number greater than 0 to enable batch tracing mode
)

messages = ["What day is today?"]

# Monitor input without validation
guardrails.observe_input(messages)

# dictionary role included messages as well supposed
guardrails.observe_input([
  {"content": "What time is now?", "role": "user"},
  {"content": "What day was yesterday?", "role": "user"},
])

# `GuardableMessage` type input as well
guardrails.observe_input([
  GuardableMessage(content="How's the weather?", role="user"),
  GuardableMessage(content="Translate *cat* to Japanese.", role="user"),
])

# Call OpenAI API with original messages
api_response = await httpx.AsyncClient(
    base_url=f"https://api.openai.com/v1",
).post(
    url=f"/chat/completions",
    json={
        "model": "gpt-4o",
        "messages": [
            {
                "role": "user",
                "content": msg,
            }
            for msg in messages
        ],
    },
)

# Extract model responses
responses = [
    c.get("message", {}).get("content", "")
    for c in api_response.json().get("choices", [])
]

# Monitor output without validation
guardrails.observe_output(messages, responses)
```

### Observers

Observers provide automated monitoring by intercepting LLM client calls directly, without requiring changes to your API calling code.

#### OpenAI Client Observer

```python
from atlas_guardrails.observers.openai import OpenAIObserver
from openai import OpenAI

# Initialize observer
observer = OpenAIObserver(
    alltrue_api_key="<API_KEY>",
    alltrue_endpoint_identifier="<IDENTIFIER>",
    blocking=False,  # Set to True to validate and potentially block requests
    trace=True,      # Ask the backend to record processing traces (default True)
    logging_level="WARNING",
    _batch_size=5,   # Valid when in non-blocking mode, enable sending traces in batches of up to the given size
)

# Register observer - from this point, all OpenAI client calls will be monitored
observer.register()

# Use OpenAI client as normal - monitoring happens automatically
completion = OpenAI().chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {
            "role": "user",
            "content": "What day is today?",
        }
    ],
)

# Optional: unregister when monitoring is no longer needed
observer.unregister()
```

##### Require-approval (HOLD) in blocking mode

When `blocking=True` and a guardrail policy holds a turn for human approval, the
backend returns an approval-prompt completion instead of the model's answer — the
observer hands that completion straight back to the caller and **does not call the
LLM**. The returned `completion` carries the approval prompt as the assistant
message; surface it to the user and send their reply (`yes` / `no`) as the next
turn to resolve the hold. The same applies once a held turn resolves (the backend
returns the final completion directly). No extra code is needed — it flows through
the normal `create(...)` return value.

### Traceability

Pass a `chat_id` to correlate an input with its corresponding output, and to retrieve the
processing trace later. The `guard_*` / `observe_*` methods accept `trace=True` (the default)
to ask the backend to record the trace; set `trace=False` to opt out.

```python
import uuid

chat_id = uuid.uuid4()

# Tag the input and output of the same conversation with one id
guarded_input = await guardrails.guard_input(messages, chat_id=chat_id)
guarded_output = await guardrails.guard_output(messages, responses, chat_id=chat_id)

# Retrieve the recorded trace for that conversation (None if no match yet)
trace = await guardrails.trace(chat_id)
```

## Features

- **Input and Output Monitoring**: Track all interactions with LLM APIs
- **Content Validation**: Ensure compliance with your usage policies
- **Blocking Mode**: Optionally prevent non-compliant requests or responses
- **Seamless Integration**: Minimal changes to existing code
- **Asynchronous Support**: Works with both synchronous and asynchronous code
- **Multiple Integration Options**: Use guardrails for explicit validation or observers for automatic monitoring
- **Traceability**: Correlate inputs and outputs via a `chat_id` and retrieve processing traces

## Troubleshooting

- **Configuration Issues**: Ensure all required parameters or environment variables are correctly set
- **Permission Errors**: Verify your API keys have the necessary permissions
- **Performance Considerations**: In blocking mode, requests will wait for validation, which may add latency


## Releasing

`atlas-guardrails` and `atlas-guardrails-core` are versioned and published together. Pushes to
`develop` produce alpha pre-releases (`pip install --pre atlas-guardrails`) and the `develop → main`
PR cuts the final release. See [docs/RELEASING.md](docs/RELEASING.md) for the full branching model,
conventional-commit rules, and CI/CD setup.

## License

This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
