orbitals 0.0.3__py3-none-any.whl → 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -17,7 +17,7 @@ from ..modeling import (
17
17
  ScopeGuardOutput,
18
18
  )
19
19
 
20
- DefaultModel = Literal["scope-guard"]
20
+ DefaultModel = Literal["small"]
21
21
 
22
22
  MODEL_MAPPING = {
23
23
  "scope-guard": "principled-intelligence/scope-guard-4B-q-2601",
@@ -137,7 +137,7 @@ class ScopeGuard(BaseScopeGuard):
137
137
  def __new__(
138
138
  cls,
139
139
  backend: Literal["hf"] = "hf",
140
- model: DefaultModel | str = "scope-guard",
140
+ model: DefaultModel | str = "small",
141
141
  skip_evidences: bool = False,
142
142
  max_new_tokens: int = 10_000,
143
143
  do_sample: bool = False,
@@ -148,7 +148,7 @@ class ScopeGuard(BaseScopeGuard):
148
148
  def __new__(
149
149
  cls,
150
150
  backend: Literal["vllm"],
151
- model: DefaultModel | str = "scope-guard",
151
+ model: DefaultModel | str = "small",
152
152
  skip_evidences: bool = False,
153
153
  temperature: float = 0.0,
154
154
  max_tokens: int = 10_000,
@@ -223,7 +223,7 @@ class AsyncScopeGuard(BaseScopeGuard):
223
223
  def __new__(
224
224
  cls,
225
225
  backend: Literal["vllm-api"],
226
- model: DefaultModel | str = "scope-guard",
226
+ model: DefaultModel | str = "small",
227
227
  skip_evidences: bool = False,
228
228
  vllm_serving_url: str = "http://localhost:8000",
229
229
  temperature: float = 0.0,
@@ -21,7 +21,7 @@ class HuggingFaceScopeGuard(ScopeGuard):
21
21
  def __init__(
22
22
  self,
23
23
  backend: Literal["hf"] = "hf",
24
- model: DefaultModel | str = "scope-guard",
24
+ model: DefaultModel | str = "small",
25
25
  skip_evidences: bool = False,
26
26
  max_new_tokens: int = 10_000,
27
27
  do_sample: bool = False,
@@ -23,7 +23,7 @@ class VLLMScopeGuard(ScopeGuard):
23
23
  def __init__(
24
24
  self,
25
25
  backend: Literal["vllm"] = "vllm",
26
- model: DefaultModel | str = "scope-guard",
26
+ model: DefaultModel | str = "small",
27
27
  skip_evidences: bool = False,
28
28
  temperature: float = 0.0,
29
29
  max_tokens: int = 10_000,
@@ -127,7 +127,7 @@ class AsyncVLLMApiScopeGuard(AsyncScopeGuard):
127
127
  def __init__(
128
128
  self,
129
129
  backend: Literal["vllm-api", "vllm-async-api"] = "vllm-api",
130
- model: DefaultModel | str = "scope-guard",
130
+ model: DefaultModel | str = "small",
131
131
  skip_evidences: bool = False,
132
132
  vllm_serving_url: str = "http://localhost:8000",
133
133
  temperature: float = 0.0,
orbitals/types.py CHANGED
@@ -1,46 +1,34 @@
1
- from typing import ClassVar, Literal
1
+ from typing import Literal
2
2
 
3
- from pydantic import BaseModel, ConfigDict, Field
3
+ from pydantic import BaseModel, Field
4
4
 
5
5
 
6
6
  class LLMUsage(BaseModel):
7
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
8
-
9
7
  prompt_tokens: int
10
8
  completion_tokens: int
11
9
  total_tokens: int
12
10
 
13
11
 
14
12
  class ConversationMessage(BaseModel):
15
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
16
-
17
13
  role: Literal["user", "assistant"]
18
14
  content: str
19
15
 
20
16
 
21
17
  class Conversation(BaseModel):
22
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
23
-
24
18
  messages: list[ConversationMessage]
25
19
 
26
20
 
27
21
  class SupportingMaterial(BaseModel):
28
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
29
-
30
22
  pass
31
23
 
32
24
 
33
25
  class Principle(BaseModel):
34
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
35
-
36
26
  title: str = Field(description="Title of the principle")
37
27
  description: str = Field(description="Description of the principle")
38
28
  supporting_materials: list[SupportingMaterial] | None
39
29
 
40
30
 
41
31
  class AIServiceDescription(BaseModel):
42
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
43
-
44
32
  identity_role: str = Field(
45
33
  description="Identity, role and objectives of the AI Service. Gives a general idea of what the service is about."
46
34
  )
orbitals/utils.py CHANGED
@@ -1,5 +1,14 @@
1
1
  import logging
2
2
  import os
3
+ from typing import TYPE_CHECKING
4
+
5
+ if TYPE_CHECKING:
6
+ import torch
7
+ else:
8
+ try:
9
+ import torch # ty: ignore[unresolved-import]
10
+ except ModuleNotFoundError:
11
+ torch = None # ty: ignore[invalid-assignment]
3
12
 
4
13
 
5
14
  def maybe_configure_gpu_usage():
@@ -7,47 +16,30 @@ def maybe_configure_gpu_usage():
7
16
  If the user hasn't explicitly set CUDA_VISIBLE_DEVICES, auto-configure it for
8
17
  optimal usage: search for the gpu with the most free memory, and
9
18
  set CUDA_VISIBLE_DEVICES to that GPU only.
10
-
11
- Uses pynvml to avoid triggering CUDA initialization from torch.
12
19
  """
20
+ if torch is None:
21
+ return
22
+
13
23
  if "CUDA_VISIBLE_DEVICES" in os.environ:
14
24
  logging.info(
15
25
  "CUDA_VISIBLE_DEVICES is already set, not auto-configuring GPU usage"
16
26
  )
17
27
  return
18
28
 
19
- try:
20
- import pynvml # ty: ignore[unresolved-import]
21
- except ModuleNotFoundError:
22
- logging.debug("pynvml not available, skipping GPU auto-configuration")
29
+ if not torch.cuda.is_available():
23
30
  return
24
31
 
25
- try:
26
- pynvml.nvmlInit()
27
- except pynvml.NVMLError:
28
- logging.debug("NVML initialization failed, skipping GPU auto-configuration")
29
- return
32
+ best_idx = None
33
+ best_free = -1
30
34
 
31
- try:
32
- device_count = pynvml.nvmlDeviceGetCount()
33
- if device_count == 0:
34
- return
35
-
36
- best_idx = None
37
- best_free = -1
38
-
39
- for i in range(device_count):
40
- handle = pynvml.nvmlDeviceGetHandleByIndex(i)
41
- mem_info = pynvml.nvmlDeviceGetMemoryInfo(handle)
42
- if mem_info.free > best_free:
43
- best_idx = i
44
- best_free = mem_info.free
45
-
46
- if best_idx is not None:
47
- if device_count > 1:
48
- logging.warning(
49
- f"Auto-configuring to use GPU {best_idx} with {best_free / 1024**3:.2f} GB free"
50
- )
51
- os.environ["CUDA_VISIBLE_DEVICES"] = str(best_idx)
52
- finally:
53
- pynvml.nvmlShutdown()
35
+ for i in range(torch.cuda.device_count()):
36
+ free_bytes, _ = torch.cuda.mem_get_info(i) # (free, total)
37
+ if free_bytes > best_free:
38
+ best_idx = i
39
+ best_free = free_bytes
40
+
41
+ if best_idx is not None:
42
+ logging.warning(
43
+ f"Auto-configuring VLLM to use GPU {best_idx} with {best_free / 1024**3:.2f} GB free"
44
+ )
45
+ os.environ["CUDA_VISIBLE_DEVICES"] = str(best_idx)
@@ -0,0 +1,103 @@
1
+ Metadata-Version: 2.4
2
+ Name: orbitals
3
+ Version: 0.1.0
4
+ Summary: LLM Guardrails tailored to your Principles
5
+ Author-email: Luigi Procopio <luigi@principled-intelligence.com>, Edoardo Barba <edoardo@principled-intelligence.com>
6
+ License: Apache-2.0
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.10
9
+ Requires-Dist: aiohttp
10
+ Requires-Dist: pydantic>=2.0.0
11
+ Requires-Dist: requests
12
+ Requires-Dist: typer>=0.12.3
13
+ Provides-Extra: scope-guard-hf
14
+ Requires-Dist: accelerate>=1.11.0; extra == 'scope-guard-hf'
15
+ Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-hf'
16
+ Provides-Extra: scope-guard-serve
17
+ Requires-Dist: fastapi[standard]>=0.119.1; extra == 'scope-guard-serve'
18
+ Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-serve'
19
+ Requires-Dist: uvicorn>=0.29.0; extra == 'scope-guard-serve'
20
+ Requires-Dist: vllm>=0.11.0; extra == 'scope-guard-serve'
21
+ Requires-Dist: xgrammar; extra == 'scope-guard-serve'
22
+ Provides-Extra: scope-guard-vllm
23
+ Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-vllm'
24
+ Requires-Dist: vllm>=0.11.0; extra == 'scope-guard-vllm'
25
+ Requires-Dist: xgrammar; extra == 'scope-guard-vllm'
26
+ Description-Content-Type: text/markdown
27
+
28
+ <div align="center">
29
+ <img src="assets/orbitals.svg" width="40%" />
30
+ <h3 align="center">
31
+ <p>
32
+ <b>LLM Guardrails tailored to your Principles</b>
33
+ </p>
34
+ </h4>
35
+ <hr/>
36
+ </div>
37
+
38
+ <p align="center">
39
+ <img src="https://img.shields.io/badge/type%20checked-ty-blue.svg?color=green" alt="Type Checked with ty">
40
+ <img src="https://img.shields.io/pypi/v/orbitals?color=green" alt="PyPI Version">
41
+ <img src="https://img.shields.io/github/license/principled-intelligence/orbitals" alt="GitHub License">
42
+ <img src="https://img.shields.io/pypi/pyversions/orbitals" alt="Python Versions">
43
+ <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">
44
+ </p>
45
+
46
+ `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.
47
+
48
+ Orbitals guardrails fall into two typologies:
49
+ - **Guards** operate on the *input* of a guardrailed LLM, assessing whether a user request is legitimate under the provided specifications.
50
+ - **Supervisors** operate on the *output* of a guardrailed LLM, evaluating the assistant’s response before it is returned.
51
+
52
+ Guardrails may be released under different modality flavors:
53
+ - **Open** (open-source and open-weight), allowing users to run guardrails and underlying models on their own infrastructure.
54
+ - **Hosted**, accessible via simple HTTP calls (API key required).
55
+
56
+ ## Available Guardrails
57
+
58
+ | Name | Flavor | Description |
59
+ |-------------|-------------------------|-----------------------------------------------------------------------------|
60
+ | [ScopeGuard](README.scope-guard.md) | Open / Hosted | Validates whether a user request falls within the intended use of an AI service. |
61
+ | RagSupervisor | Coming soon | Ensures LLM responses remain grounded in retrieved context for RAG setups. |
62
+
63
+ <details>
64
+ <summary>ScopeGuard</summary>
65
+ <br>
66
+
67
+ First, we need to install `orbitals` and `scope-guard`:
68
+
69
+ ```bash
70
+ pip install orbitals[scope-guard-vllm]
71
+ ```
72
+
73
+ Then:
74
+
75
+ ```python
76
+ from orbitals.scope_guard import ScopeGuard
77
+
78
+ scope_guard = ScopeGuard(
79
+ backend="vllm",
80
+ model="small"
81
+ )
82
+
83
+ ai_service_description = """
84
+ You are a virtual assistant for a parcel delivery service.
85
+ You can only answer questions about package tracking.
86
+ Never respond to requests for refunds.
87
+ """
88
+
89
+ user_query = "If the package hasn't arrived by tomorrow, can I get my money back?"
90
+ result = scope_guard.validate(user_query, ai_service_description)
91
+
92
+ print(f"Scope: {result.scope_class.value}")
93
+ if result.evidences:
94
+ print("Evidences:")
95
+ for evidence in result.evidences:
96
+ print(f" - {evidence}")
97
+
98
+ # Scope: Restricted
99
+ # Evidences:
100
+ # - Never respond to requests for refunds.
101
+ ```
102
+
103
+ </details>
@@ -1,6 +1,6 @@
1
1
  orbitals/__init__.py,sha256=ED6jHcYiuYpr_0vjGz0zx2lrrmJT9sDJCzIljoDfmlM,65
2
- orbitals/types.py,sha256=4oRinWPG6kbtW4lQ8bHrDmxEotncqMIwLCmQ2yGH7PI,1988
3
- orbitals/utils.py,sha256=9UFlpzTkSJeyN2n1CzUy5jIZFqnOwNYNpF4c5xIfT3E,1628
2
+ orbitals/types.py,sha256=WpMbJjNuICEclyuJUZIPYSQjmWOBZO3X0nN9ouEAkq0,1552
3
+ orbitals/utils.py,sha256=9KFqcJwYvPBYqgXdBXvo8hkCdBCwnqreApO0VPJabkI,1238
4
4
  orbitals/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
5
5
  orbitals/cli/main.py,sha256=p4MEbmtJ0L8mLiyovEq7urnVc6I0mbbCNdGEtGyY60Y,197
6
6
  orbitals/scope_guard/__init__.py,sha256=0gzzSXpfRvIcCYpu3AKQSMFYDMDJaknY9pdypt7HiuI,197
@@ -12,14 +12,14 @@ orbitals/scope_guard/cli/main.py,sha256=jz8fQ2e4VFZQti982feVWGpL9fT7yZeanq14pX5W
12
12
  orbitals/scope_guard/cli/serve.py,sha256=EM6yNSviwot8Im-MG1_AA4PsOkZXW9W2CmokqNfq7es,4611
13
13
  orbitals/scope_guard/guards/__init__.py,sha256=B1EA9YtaTQ3ko5d2wFK2y4bXKrV8MclAELAievmZjxg,376
14
14
  orbitals/scope_guard/guards/api.py,sha256=S8VX4_8VIhtg3_IP4Eh50l1uarcJBagGXNEEl1BZjag,8514
15
- orbitals/scope_guard/guards/base.py,sha256=5DQeOY7kvTgH6GSExMpy3b_KQtNWzSlrudro6giQ-Ec,9798
16
- orbitals/scope_guard/guards/hf.py,sha256=xFNl_DtRiePB3n3V2spsSwiRRYz1qZYNw-wQTyiZsCI,3967
17
- orbitals/scope_guard/guards/vllm.py,sha256=3LU9DKKniQd90Ibaq2Wef20fyoZXgkeQtc58XY6kX2I,8983
15
+ orbitals/scope_guard/guards/base.py,sha256=HV0XuYRQ1z5MG4enER05f8D6UrcRrQsz54nZpHlNa94,9774
16
+ orbitals/scope_guard/guards/hf.py,sha256=L6QlJjHa1HW3-SJ9YL5mtVMtL253yp90pNTX2E9t1Qw,3961
17
+ orbitals/scope_guard/guards/vllm.py,sha256=YbCE6EMpLvymueXCY3gHKdDarJHiv1nl4miC0PWBIPI,8971
18
18
  orbitals/scope_guard/serving/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
19
19
  orbitals/scope_guard/serving/main.py,sha256=pjUol71h7CuU_6PiB7Zjdm5eNyDVH-F8bZVNeyEL-tE,3822
20
20
  orbitals/scope_guard/serving/vllm_logging_config.json,sha256=Bc08X8mQWJFAAHEE6ZFVUGnRc77pMVpPvji6BhFTtSE,651
21
- orbitals-0.0.3.dist-info/METADATA,sha256=pgtkFPmdlhU9pnorq_cfSnf0Egc36vMEbY1elxaohfU,7148
22
- orbitals-0.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
23
- orbitals-0.0.3.dist-info/entry_points.txt,sha256=fd6lukgEvK9UBwhA1JtcB9MLTqAtntA4H2cc7-nWkeU,51
24
- orbitals-0.0.3.dist-info/licenses/LICENSE,sha256=Eeclrom-K-omYcKnMvijEMV-IMiQ7X-bdgxlZcXcImI,11360
25
- orbitals-0.0.3.dist-info/RECORD,,
21
+ orbitals-0.1.0.dist-info/METADATA,sha256=UX8YQJWOpCU2BJMdklqYTOK4rAJd4yUhDDChFufRMLs,4368
22
+ orbitals-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
23
+ orbitals-0.1.0.dist-info/entry_points.txt,sha256=fd6lukgEvK9UBwhA1JtcB9MLTqAtntA4H2cc7-nWkeU,51
24
+ orbitals-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
25
+ orbitals-0.1.0.dist-info/RECORD,,
@@ -186,7 +186,7 @@
186
186
  same "printed page" as the copyright notice for easier
187
187
  identification within third-party archives.
188
188
 
189
- Copyright 2026 Principled Intelligence s.r.l.
189
+ Copyright [yyyy] [name of copyright owner]
190
190
 
191
191
  Licensed under the Apache License, Version 2.0 (the "License");
192
192
  you may not use this file except in compliance with the License.
@@ -1,161 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: orbitals
3
- Version: 0.0.3
4
- Summary: LLM Guardrails tailored to your Principles
5
- Author-email: Luigi Procopio <luigi@principled-intelligence.com>, Edoardo Barba <edoardo@principled-intelligence.com>
6
- License: Apache-2.0
7
- License-File: LICENSE
8
- Classifier: Programming Language :: Python :: 3 :: Only
9
- Classifier: Programming Language :: Python :: 3.10
10
- Classifier: Programming Language :: Python :: 3.11
11
- Classifier: Programming Language :: Python :: 3.12
12
- Classifier: Programming Language :: Python :: 3.13
13
- Classifier: Programming Language :: Python :: 3.14
14
- Requires-Python: >=3.10
15
- Requires-Dist: aiohttp
16
- Requires-Dist: pydantic>=2.0.0
17
- Requires-Dist: requests
18
- Requires-Dist: typer>=0.12.3
19
- Provides-Extra: all
20
- Requires-Dist: accelerate>=1.11.0; extra == 'all'
21
- Requires-Dist: fastapi[standard]>=0.119.1; extra == 'all'
22
- Requires-Dist: pynvml; extra == 'all'
23
- Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'all'
24
- Requires-Dist: uvicorn>=0.29.0; extra == 'all'
25
- Requires-Dist: vllm>=0.11.0; extra == 'all'
26
- Requires-Dist: xgrammar; extra == 'all'
27
- Provides-Extra: scope-guard-all
28
- Requires-Dist: accelerate>=1.11.0; extra == 'scope-guard-all'
29
- Requires-Dist: fastapi[standard]>=0.119.1; extra == 'scope-guard-all'
30
- Requires-Dist: pynvml; extra == 'scope-guard-all'
31
- Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-all'
32
- Requires-Dist: uvicorn>=0.29.0; extra == 'scope-guard-all'
33
- Requires-Dist: vllm>=0.11.0; extra == 'scope-guard-all'
34
- Requires-Dist: xgrammar; extra == 'scope-guard-all'
35
- Provides-Extra: scope-guard-hf
36
- Requires-Dist: accelerate>=1.11.0; extra == 'scope-guard-hf'
37
- Requires-Dist: pynvml; extra == 'scope-guard-hf'
38
- Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-hf'
39
- Provides-Extra: scope-guard-serve
40
- Requires-Dist: fastapi[standard]>=0.119.1; extra == 'scope-guard-serve'
41
- Requires-Dist: pynvml; extra == 'scope-guard-serve'
42
- Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-serve'
43
- Requires-Dist: uvicorn>=0.29.0; extra == 'scope-guard-serve'
44
- Requires-Dist: vllm>=0.11.0; extra == 'scope-guard-serve'
45
- Requires-Dist: xgrammar; extra == 'scope-guard-serve'
46
- Provides-Extra: scope-guard-vllm
47
- Requires-Dist: pynvml; extra == 'scope-guard-vllm'
48
- Requires-Dist: transformers<5.0.0,>=4.47.0; extra == 'scope-guard-vllm'
49
- Requires-Dist: vllm>=0.11.0; extra == 'scope-guard-vllm'
50
- Requires-Dist: xgrammar; extra == 'scope-guard-vllm'
51
- Description-Content-Type: text/markdown
52
-
53
- <div align="center">
54
- <img src="assets/orbitals-banner.png" width="70%" />
55
- <h3 align="center">
56
- <p>
57
- <b>LLM Guardrails tailored to your Principles</b>
58
- </p>
59
- </h4>
60
- </div>
61
-
62
- <p align="center">
63
- <img src="https://img.shields.io/pypi/v/orbitals?color=green" alt="PyPI Version">
64
- <!-- <img src="https://img.shields.io/badge/type%20checked-ty-blue.svg?color=green" alt="Type Checked with ty"> -->
65
- <img src="https://img.shields.io/pypi/pyversions/orbitals" alt="Python Versions">
66
- <img src="https://img.shields.io/github/license/principled-intelligence/orbitals" alt="GitHub License">
67
- </p>
68
-
69
- ## Overview
70
-
71
- **Orbitals** is a lightweight Python library for adding LLM guardrails in just a few lines of code. With Orbitals, you can add a governance layer tailored to **user-specific principles**. Rather than enforcing generic notions of safety, compliance, and correctness, Orbitals validates inputs (e.g., user requests) and outputs (e.g., assistant responses) against user-defined specifications and custom policies. This makes guardrails explicit, auditable, and aligned with the user's philosophy.
72
-
73
- ### Key Features
74
-
75
- - **User-defined specifications** — Guardrails that match your use case and your custom policies, not generic safety rules
76
- - **Simple integration** — Add guardrails with minimal code changes
77
- - **Open framework, open models** — Orbitals is open-source and is a simple interface for our open models
78
-
79
- ## Getting started
80
-
81
- ### Installation
82
-
83
- You can install Orbitals via pip:
84
-
85
- ```bash
86
- pip install orbitals[all]
87
- ```
88
-
89
- ### Basic Usage
90
-
91
- Here's a quick example to get you started with Orbitals, in which we use the ScopeGuard module to guard an AI service (for example, a customer support chatbot) from user requests that violate specified principles or fall outside of the scope of the core task of the assistant.
92
-
93
- ```python
94
- from orbitals.scope_guard import ScopeGuard
95
-
96
- ai_service_description = "You are a helpful assistant for ..."
97
- user_message = "Can I buy ..."
98
-
99
- guardrail = ScopeGuard()
100
- result = guardrail.validate(user_message, ai_service_description)
101
- ```
102
-
103
- The result of a guardrail validation will indicate whether the input or output passed the guardrail checks, along with details on any violations. You can then handle violations as needed, such as by rejecting the input or modifying the output. For example:
104
-
105
- ```python
106
- if result.scope_class.value == "Restricted" or result.scope_class.value == "Out of Scope":
107
- print("Request violates guardrail:", result.evidences)
108
- else:
109
- # The user request is safe!
110
- # We can now pass it to the AI assistant for processing.
111
- ...
112
- ```
113
-
114
- ### Available Guardrails
115
-
116
- Orbitals currently provides the following guardrail modules:
117
-
118
- | Guardrail | Description | Hosting Options |
119
- |:----------|:------------|:----------------|
120
- | **[ScopeGuard](README.scope-guard.md)** | Classifies user queries against AI assistant specifications to detect out-of-scope requests, policy violations, and chit-chat | Self-hosted / Cloud hosting |
121
- | 🚀 *Coming Soon* | More guardrails are on the way — stay tuned for updates! | — |
122
-
123
- #### Hosting Options
124
-
125
- - **Self-hosted**: Use open-weight models that you can deploy on your own infrastructure, ensuring data privacy and control.
126
- - **Cloud hosting**: (Coming soon) Managed hosting options for ease of use and scalability
127
-
128
- ### Documentation
129
-
130
- For detailed documentation, including installation instructions, usage guides, and API references, please visit the Orbitals Documentation.
131
-
132
- - [ScopeGuard Documentation](README.scope-guard.md)
133
-
134
- ### FAQ
135
-
136
- - **Can I use Orbitals for commercial applications?**
137
- Yes, Orbitals is designed to be used in both research and commercial applications. It is licensed under the Apache 2.0 License, which allows for commercial use.
138
- - **Other questions?**
139
- Feel free to reach out to us at [orbitals@principled-intelligence.com](mailto:orbitals@principled-intelligence.com)!
140
-
141
- ### Contributing
142
-
143
- We welcome contributions from the community! If you'd like to contribute to Orbitals, please check out our [Contributing Guide](CONTRIBUTING.md) for guidelines on how to get started.
144
-
145
- ### License
146
-
147
- This project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.
148
-
149
- ### Contact
150
-
151
- For questions, feedback, or support, please reach out to us at [orbitals@principled-intelligence.com](mailto:orbitals@principled-intelligence.com).
152
-
153
- ---
154
-
155
- <div align="center">
156
- <p>
157
- <b>Built with ❤️ by <a href="https://principled-intelligence.com">Principled Intelligence</a></b>
158
- <br />
159
- Follow us on <a href="https://www.linkedin.com/company/principled-ai/">LinkedIn</a> for the latest updates.
160
- </p>
161
- </div>