Metadata-Version: 2.4
Name: orbitals
Version: 0.0.2
Summary: LLM Guardrails tailored to your Principles
Author-email: Luigi Procopio <luigi@principled-intelligence.com>, Edoardo Barba <edoardo@principled-intelligence.com>
License: Apache-2.0
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: aiohttp
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests
Requires-Dist: typer>=0.12.3
Provides-Extra: all
Requires-Dist: accelerate>=1.11.0; extra == 'all'
Requires-Dist: fastapi[standard]>=0.119.1; extra == 'all'
Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'all'
Requires-Dist: uvicorn>=0.29.0; extra == 'all'
Requires-Dist: vllm>=0.11.0; extra == 'all'
Requires-Dist: xgrammar; extra == 'all'
Provides-Extra: scope-guard-all
Requires-Dist: accelerate>=1.11.0; extra == 'scope-guard-all'
Requires-Dist: fastapi[standard]>=0.119.1; extra == 'scope-guard-all'
Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-all'
Requires-Dist: uvicorn>=0.29.0; extra == 'scope-guard-all'
Requires-Dist: vllm>=0.11.0; extra == 'scope-guard-all'
Requires-Dist: xgrammar; extra == 'scope-guard-all'
Provides-Extra: scope-guard-hf
Requires-Dist: accelerate>=1.11.0; extra == 'scope-guard-hf'
Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-hf'
Provides-Extra: scope-guard-serve
Requires-Dist: fastapi[standard]>=0.119.1; extra == 'scope-guard-serve'
Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-serve'
Requires-Dist: uvicorn>=0.29.0; extra == 'scope-guard-serve'
Requires-Dist: vllm>=0.11.0; extra == 'scope-guard-serve'
Requires-Dist: xgrammar; extra == 'scope-guard-serve'
Provides-Extra: scope-guard-vllm
Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-vllm'
Requires-Dist: vllm>=0.11.0; extra == 'scope-guard-vllm'
Requires-Dist: xgrammar; extra == 'scope-guard-vllm'
Description-Content-Type: text/markdown

<div align="center">
    <img src="assets/orbitals-banner.png" width="70%" />
    <h3 align="center">
        <p>
            <b>LLM Guardrails tailored to your Principles</b>
        </p>
    </h4>
    <hr/>
</div>

<p align="center">
    <img src="https://img.shields.io/badge/type%20checked-ty-blue.svg?color=green" alt="Type Checked with ty">
    <img src="https://img.shields.io/pypi/v/orbitals?color=green" alt="PyPI Version">
    <img src="https://img.shields.io/github/license/principled-intelligence/orbitals" alt="GitHub License">
    <img src="https://img.shields.io/pypi/pyversions/orbitals" alt="Python Versions">
    <img src="https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fprincipled-intelligence%2Forbitals%2Fmain%2Fpyproject.toml" alt="Required Python Version">
</p>

`orbitals` is an ecosystem of LLM guardrails, designed to provide a governance layer tailored to **user-specific principles, requirements and use cases**. Rather than enforcing generic notions of safety, correctness, etc., Orbitals evaluates inputs and outputs against *user-defined specifications*. This makes guardrails explicit, auditable, and aligned with the user's philosophy.

Orbitals guardrails fall into two typologies:
- **Guards** operate on the *input* of a guardrailed LLM, assessing whether a user request is legitimate under the provided specifications.
- **Supervisors** operate on the *output* of a guardrailed LLM, evaluating the assistant’s response before it is returned.

Guardrails may be released under different modality flavors:
- **Open** (open-source and open-weight), allowing users to run guardrails and underlying models on their own infrastructure.
- **Hosted**, accessible via simple HTTP calls (API key required).

## Available Guardrails

| Name        | Flavor                  | Description                                                                 |
|-------------|-------------------------|-----------------------------------------------------------------------------|
| [ScopeGuard](README.scope-guard.md)  | Open / Hosted           | Validates whether a user request falls within the intended use of an AI service. |
| RagSupervisor    | Coming soon             | Ensures LLM responses remain grounded in retrieved context for RAG setups. |

<details>
<summary>ScopeGuard</summary>
<br>

First, we need to install `orbitals` and `scope-guard`:

```bash
pip install orbitals[scope-guard-vllm]
```

Then:

```python
from orbitals.scope_guard import ScopeGuard

scope_guard = ScopeGuard(
    backend="vllm",
    model="scope-guard-q",    # for the Qwen-family model
    # model="scope-guard-g",  # for the Gemma-family model
)

ai_service_description = """
You are a virtual assistant for a parcel delivery service.
You can only answer questions about package tracking.
Never respond to requests for refunds.
"""

user_query = "If the package hasn't arrived by tomorrow, can I get my money back?"
result = scope_guard.validate(user_query, ai_service_description)

print(f"Scope: {result.scope_class.value}")
if result.evidences:
    print("Evidences:")
    for evidence in result.evidences:
        print(f"  - {evidence}")

# Scope: Restricted
# Evidences:
#   - Never respond to requests for refunds.
```

</details>
