Metadata-Version: 2.1
Name: atlas-guardrails
Version: 0.4.0a6
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.0a6
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. Track, validate, and secure your LLM API calls with minimal — often zero —
changes to your existing application code.

- **Observers** wrap your LLM client so traffic is monitored automatically, no call-site changes.
- **Guardrails** give you explicit `guard`/`observe` calls when you want fine-grained control.
- **Blocking mode** can enforce policy (rewrite or block non-compliant requests/responses).
- **Traceability** correlates inputs and outputs and records processing traces.

## Installation

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

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

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

`atlas-guardrails` automatically pulls in its companion package `atlas-guardrails-core` at
the same version; both share the `atlas_guardrails` import namespace.

<details>
<summary>Editable / development install</summary>

```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]"
```
</details>

## Quickstart

Set your credentials (created in the Atlas application):

```shell
export ALLTRUE_API_KEY="<your-api-key>"
export ALLTRUE_ENDPOINT_IDENTIFIER="<your-endpoint-identifier>"
```

Then monitor every OpenAI chat completion with no changes to your call sites:

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

observer = OpenAIObserver(
    alltrue_api_key=os.environ["ALLTRUE_API_KEY"],
    alltrue_endpoint_identifier=os.environ["ALLTRUE_ENDPOINT_IDENTIFIER"],
    blocking=False,  # monitor only; set True to enforce policy
)
observer.register()

# Your existing code — now observed automatically.
completion = OpenAI().chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What day is today?"}],
)
print(completion.choices[0].message.content)

observer.unregister()
```

Prefer explicit validation instead of patching the client? Use `ChatGuardrails`:

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

guardrails = ChatGuardrails(
    alltrue_api_key=os.environ["ALLTRUE_API_KEY"],
    alltrue_endpoint_identifier=os.environ["ALLTRUE_ENDPOINT_IDENTIFIER"],
)

try:
    guarded = await guardrails.guard_input(["What day is today?"])
except GuardrailsException as exc:
    print(f"Input blocked: {exc}")
```

## Configuration essentials

| Setting | Constructor arg | Env var | Required |
|---------|-----------------|---------|----------|
| API key | `alltrue_api_key` | `ALLTRUE_API_KEY` | **Yes** |
| Endpoint identifier | `alltrue_endpoint_identifier` | `ALLTRUE_ENDPOINT_IDENTIFIER` | **Yes** |
| API base URL | `alltrue_api_url` | `ALLTRUE_API_URL` | No (defaults to the Atlas production endpoint) |

Constructor arguments win over environment variables, and a `.env` file in the working
directory is loaded automatically. See the **[full configuration reference](docs/USAGE.md#configuration)**
for every option (logging, blocking, batching, timeouts, control directives).

## Documentation

- **[docs/USAGE.md](docs/USAGE.md)** — full usage guide: observers, guardrails, blocking
  vs non-blocking, batch mode, control directives, traceability, and troubleshooting.
- **[docs/RELEASING.md](docs/RELEASING.md)** — versioning, branching model, and CI/CD.

## Features

- **Zero-touch observers** for the OpenAI client (sync and async).
- **Explicit guardrails** for custom pipelines and non-OpenAI flows.
- **Blocking mode** to validate and, if needed, rewrite or block requests/responses.
- **Require-approval (HOLD)** flow for human-in-the-loop policies.
- **Traceability** via a `chat_id` plus retrievable processing traces.
- **Batch mode** to reduce request volume when monitoring.
- **Async and sync** support.

## Releasing

`atlas-guardrails` and `atlas-guardrails-core` are versioned and published together. Pushes
to `develop` produce alpha pre-releases (`pip install --pre atlas-guardrails`); 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.
</content>
