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

orbitals/types.py

@@ -1,34 +1,46 @@
-from typing import Literal
+from typing import ClassVar, Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class LLMUsage(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
     prompt_tokens: int
     completion_tokens: int
     total_tokens: int
 
 
 class ConversationMessage(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
     role: Literal["user", "assistant"]
     content: str
 
 
 class Conversation(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
     messages: list[ConversationMessage]
 
 
 class SupportingMaterial(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
     pass
 
 
 class Principle(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
     title: str = Field(description="Title of the principle")
     description: str = Field(description="Description of the principle")
     supporting_materials: list[SupportingMaterial] | None
 
 
 class AIServiceDescription(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
     identity_role: str = Field(
         description="Identity, role and objectives of the AI Service. Gives a general idea of what the service is about."
     )

orbitals/utils.py

@@ -1,14 +1,5 @@
 import logging
 import os
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    import torch
-else:
-    try:
-        import torch  # ty: ignore[unresolved-import]
-    except ModuleNotFoundError:
-        torch = None  # ty: ignore[invalid-assignment]
 
 
 def maybe_configure_gpu_usage():
@@ -16,30 +7,47 @@ def maybe_configure_gpu_usage():
     If the user hasn't explicitly set CUDA_VISIBLE_DEVICES, auto-configure it for
     optimal usage: search for the gpu with the most free memory, and
     set CUDA_VISIBLE_DEVICES to that GPU only.
-    """
-    if torch is None:
-        return
 
+    Uses pynvml to avoid triggering CUDA initialization from torch.
+    """
     if "CUDA_VISIBLE_DEVICES" in os.environ:
         logging.info(
             "CUDA_VISIBLE_DEVICES is already set, not auto-configuring GPU usage"
         )
         return
 
-    if not torch.cuda.is_available():
+    try:
+        import pynvml  # ty: ignore[unresolved-import]
+    except ModuleNotFoundError:
+        logging.debug("pynvml not available, skipping GPU auto-configuration")
         return
 
-    best_idx = None
-    best_free = -1
-
-    for i in range(torch.cuda.device_count()):
-        free_bytes, _ = torch.cuda.mem_get_info(i)  # (free, total)
-        if free_bytes > best_free:
-            best_idx = i
-            best_free = free_bytes
+    try:
+        pynvml.nvmlInit()
+    except pynvml.NVMLError:
+        logging.debug("NVML initialization failed, skipping GPU auto-configuration")
+        return
 
-    if best_idx is not None:
-        logging.warning(
-            f"Auto-configuring VLLM to use GPU {best_idx} with {best_free / 1024**3:.2f} GB free"
-        )
-        os.environ["CUDA_VISIBLE_DEVICES"] = str(best_idx)
+    try:
+        device_count = pynvml.nvmlDeviceGetCount()
+        if device_count == 0:
+            return
+
+        best_idx = None
+        best_free = -1
+
+        for i in range(device_count):
+            handle = pynvml.nvmlDeviceGetHandleByIndex(i)
+            mem_info = pynvml.nvmlDeviceGetMemoryInfo(handle)
+            if mem_info.free > best_free:
+                best_idx = i
+                best_free = mem_info.free
+
+        if best_idx is not None:
+            if device_count > 1:
+                logging.warning(
+                    f"Auto-configuring to use GPU {best_idx} with {best_free / 1024**3:.2f} GB free"
+                )
+            os.environ["CUDA_VISIBLE_DEVICES"] = str(best_idx)
+    finally:
+        pynvml.nvmlShutdown()

orbitals-0.0.3.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: orbitals
+Version: 0.0.3
+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: pynvml; 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: pynvml; 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: pynvml; 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: pynvml; 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: pynvml; 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>
+</div>
+
+<p align="center">
+    <img src="https://img.shields.io/pypi/v/orbitals?color=green" alt="PyPI Version">
+    <!-- <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/pyversions/orbitals" alt="Python Versions">
+    <img src="https://img.shields.io/github/license/principled-intelligence/orbitals" alt="GitHub License">
+</p>
+
+## Overview
+
+**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.
+
+### Key Features
+
+- **User-defined specifications** — Guardrails that match your use case and your custom policies, not generic safety rules
+- **Simple integration** — Add guardrails with minimal code changes
+- **Open framework, open models** — Orbitals is open-source and is a simple interface for our open models
+
+## Getting started
+
+### Installation
+
+You can install Orbitals via pip:
+
+```bash
+pip install orbitals[all]
+```
+
+### Basic Usage
+
+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.
+
+```python
+from orbitals.scope_guard import ScopeGuard
+
+ai_service_description = "You are a helpful assistant for ..."
+user_message = "Can I buy ..."
+
+guardrail = ScopeGuard()
+result = guardrail.validate(user_message, ai_service_description)
+```
+
+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:
+
+```python
+if result.scope_class.value == "Restricted" or result.scope_class.value == "Out of Scope":
+    print("Request violates guardrail:", result.evidences)
+else:
+    # The user request is safe!
+    # We can now pass it to the AI assistant for processing.
+    ...
+```
+
+### Available Guardrails
+
+Orbitals currently provides the following guardrail modules:
+
+| Guardrail | Description | Hosting Options |
+|:----------|:------------|:----------------|
+| **[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 |
+| 🚀 *Coming Soon* | More guardrails are on the way — stay tuned for updates! | — |
+
+#### Hosting Options
+
+- **Self-hosted**: Use open-weight models that you can deploy on your own infrastructure, ensuring data privacy and control.
+- **Cloud hosting**: (Coming soon) Managed hosting options for ease of use and scalability
+
+### Documentation
+
+For detailed documentation, including installation instructions, usage guides, and API references, please visit the Orbitals Documentation.
+
+- [ScopeGuard Documentation](README.scope-guard.md)
+
+### FAQ
+
+- **Can I use Orbitals for commercial applications?**  
+  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.
+- **Other questions?**  
+  Feel free to reach out to us at [orbitals@principled-intelligence.com](mailto:orbitals@principled-intelligence.com)!
+
+### Contributing
+
+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.
+
+### License
+
+This project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.
+
+### Contact
+
+For questions, feedback, or support, please reach out to us at [orbitals@principled-intelligence.com](mailto:orbitals@principled-intelligence.com).
+
+---
+
+<div align="center">
+    <p>
+        <b>Built with ❤️ by <a href="https://principled-intelligence.com">Principled Intelligence</a></b>
+        <br />
+        Follow us on <a href="https://www.linkedin.com/company/principled-ai/">LinkedIn</a> for the latest updates.
+    </p>
+</div>

{orbitals-0.0.1.dist-info → orbitals-0.0.3.dist-info}/RECORD

@@ -1,6 +1,6 @@
 orbitals/__init__.py,sha256=ED6jHcYiuYpr_0vjGz0zx2lrrmJT9sDJCzIljoDfmlM,65
-orbitals/types.py,sha256=WpMbJjNuICEclyuJUZIPYSQjmWOBZO3X0nN9ouEAkq0,1552
-orbitals/utils.py,sha256=9KFqcJwYvPBYqgXdBXvo8hkCdBCwnqreApO0VPJabkI,1238
+orbitals/types.py,sha256=4oRinWPG6kbtW4lQ8bHrDmxEotncqMIwLCmQ2yGH7PI,1988
+orbitals/utils.py,sha256=9UFlpzTkSJeyN2n1CzUy5jIZFqnOwNYNpF4c5xIfT3E,1628
 orbitals/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orbitals/cli/main.py,sha256=p4MEbmtJ0L8mLiyovEq7urnVc6I0mbbCNdGEtGyY60Y,197
 orbitals/scope_guard/__init__.py,sha256=0gzzSXpfRvIcCYpu3AKQSMFYDMDJaknY9pdypt7HiuI,197
@@ -18,8 +18,8 @@ orbitals/scope_guard/guards/vllm.py,sha256=3LU9DKKniQd90Ibaq2Wef20fyoZXgkeQtc58X
 orbitals/scope_guard/serving/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orbitals/scope_guard/serving/main.py,sha256=pjUol71h7CuU_6PiB7Zjdm5eNyDVH-F8bZVNeyEL-tE,3822
 orbitals/scope_guard/serving/vllm_logging_config.json,sha256=Bc08X8mQWJFAAHEE6ZFVUGnRc77pMVpPvji6BhFTtSE,651
-orbitals-0.0.1.dist-info/METADATA,sha256=p0OEEBeFIf3pU1eoJSuXuf0OgWKhg3rSuwDkPuzokYo,4382
-orbitals-0.0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-orbitals-0.0.1.dist-info/entry_points.txt,sha256=fd6lukgEvK9UBwhA1JtcB9MLTqAtntA4H2cc7-nWkeU,51
-orbitals-0.0.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-orbitals-0.0.1.dist-info/RECORD,,
+orbitals-0.0.3.dist-info/METADATA,sha256=pgtkFPmdlhU9pnorq_cfSnf0Egc36vMEbY1elxaohfU,7148
+orbitals-0.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+orbitals-0.0.3.dist-info/entry_points.txt,sha256=fd6lukgEvK9UBwhA1JtcB9MLTqAtntA4H2cc7-nWkeU,51
+orbitals-0.0.3.dist-info/licenses/LICENSE,sha256=Eeclrom-K-omYcKnMvijEMV-IMiQ7X-bdgxlZcXcImI,11360
+orbitals-0.0.3.dist-info/RECORD,,

{orbitals-0.0.1.dist-info → orbitals-0.0.3.dist-info}/licenses/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Principled Intelligence s.r.l.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

orbitals-0.0.1.dist-info/METADATA

@@ -1,103 +0,0 @@
-Metadata-Version: 2.4
-Name: orbitals
-Version: 0.0.1
-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
-Requires-Python: >=3.10
-Requires-Dist: aiohttp
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: requests
-Requires-Dist: typer>=0.12.3
-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"
-)
-
-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>