orbitals 0.0.2__tar.gz → 0.0.3__tar.gz

orbitals-0.0.3/.dockerignore

@@ -0,0 +1,5 @@
+.venv
+dist
+__pycache__/
+.vscode/
+examples/

orbitals-0.0.3/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to Orbitals
+
+Thank you for your interest in contributing to `orbitals`! We welcome contributions from the community.
+
+## Getting Started
+
+1. **Fork the repository** and clone it locally
+2. **Install dependencies** using `uv`:
+   ```bash
+   uv sync
+   ```
+
+## Development Workflow
+
+1. Create a new branch for your feature or fix:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes and ensure they follow the project's coding conventions
+
+3. Test your changes thoroughly
+
+4. Commit your changes with a clear, descriptive message
+
+5. Push to your fork and submit a pull request
+
+## Coding Conventions
+
+- Use **Google-style docstrings** for all documentation
+- Follow PEP 8 style guidelines
+- Keep code modular and well-organized
+
+## Reporting Issues
+
+When reporting issues, please include:
+
+- A clear description of the problem
+- Steps to reproduce the issue
+- Expected vs actual behavior
+- Your environment details (Python version, OS, etc.)
+
+## Questions?
+
+Feel free to open an issue for any questions or discussions about contributing.

{orbitals-0.0.2 → orbitals-0.0.3}/Dockerfile

@@ -25,13 +25,15 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 COPY src /app/src/
 
 RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --locked --extra serve --no-editable --no-dev
+    uv sync --locked --extra scope-guard-serve --no-editable --no-dev
 
 # TODO remove next line
 ENTRYPOINT ["/bin/bash", "-c"]
 
 FROM vllm/vllm-openai:v0.14.1 as runner
 
+ARG MODEL
+
 WORKDIR /app
 ENV PATH="/app/.venv/bin:$PATH"
 
@@ -43,4 +45,4 @@ COPY --from=builder /root/.cache/huggingface/hub /root/.cache/huggingface/hub
 EXPOSE 8000
 
 ENTRYPOINT ["/bin/bash", "-c"]
-CMD [ "orbitals", "scope-guard", "serve", "${MODEL}", "--port", "8000", "--host", "0.0.0.0" ]
+CMD [ "orbitals", "scope-guard", "serve", "principled-intelligence/${MODEL}", "--port", "8000", "--host", "0.0.0.0" ]

orbitals-0.0.3/PKG-INFO

@@ -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.3/README.md

@@ -0,0 +1,109 @@
+<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.2 → orbitals-0.0.3}/README.scope-guard.md

@@ -16,29 +16,28 @@
 </div>
 
 Given the specifications of an AI assistant and a user query, `scope-guard` maps the user query to one of the following five classes:
-*   **Directly Supported**: The query is clearly within the assistant's capabilities.
-*   **Potentially Supported**: The query could plausibly be handled by the assistant.
-*   **Out of Scope**: The query is outside the assistant's defined role.
-*   **Restricted**: The query cannot be handled due to a specific constraint.
-*   **Chit Chat**: The query is a social interaction not related to the assistant's function.
+
+* **Directly Supported**: The query is clearly within the assistant's capabilities.
+* **Potentially Supported**: The query could plausibly be handled by the assistant.
+* **Out of Scope**: The query is outside the assistant's defined role.
+* **Restricted**: The query cannot be handled due to a specific constraint.
+* **Chit Chat**: The query is a social interaction not related to the assistant's function.
 
 <p align="center">
   <img src="assets/scope-guard.svg" width="80%" />
 </p>
 
-To do this, `scope-guard` leverages specialized language models trained to evaluate whether a user query falls within an assistant’s intended scope. Different models are available, released with different modality flavors:
+To do this, `scope-guard` leverages specialized language models trained to evaluate whether a user query falls within an assistant’s intended scope. Different models are available, released with different deployment options:
 
-| Flavor | Model | Parameters | Scope Classification | Custom Safety | Vanilla Safety | Tested GPUs |
+| Model | Parameters | Hosting Options | Scope Classification | Custom Safety | Vanilla Safety | Tested GPUs |
 | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
-| Open | scope-guard-4B-q-2601 | 4B | 89.1 | 79.1 | 90,3 | T4, L4, L40S, 4090, 5090 |
-| Open | scope-guard-4B-g-2601 | 4B | 90.1 | 78.0 | 88.0 | T4, L4, L40S, 4090, 5090 |
-| Closed | scope-guard-pro | ~ | 91.9 | 81.8 | 92.0 | ~ |
+| scope-guard-4B-q-2601 | 4B | Self-hosted | 89.1 | 79.1 | 90.3 | T4, L4, L40S, 4090, 5090 |
+| scope-guard-4B-g-2601 | 4B | Self-hosted | 90.1 | 78.0 | 88.0 | T4, L4, L40S, 4090, 5090 |
+| scope-guard-pro | ~ | Cloud-only | 91.9 | 81.8 | 92.0 | ~ |
 
-## Quickstart
+## Quickstart with our open models
 
-<details open>
-<summary>Open Flavor</summary>
-<br>
+The easiest way to get started with ScopeGuard is to use our open models, which you can self-host on consumer-grade GPUs (e.g., Nvidia RTX series) and use via the `vllm` or `huggingface` backends. `scope-guard-4B-q-2601` and `scope-guard-4B-g-2601` are both 4B-parameter models so they can run even on a free instance on Google Colab with a T4 GPU.
 
 First, we need to install `orbitals` and `scope-guard`:
 
@@ -53,7 +52,7 @@ Then:
 ```python
 from orbitals.scope_guard import ScopeGuard
 
-scope_guard = ScopeGuard(
+sg = ScopeGuard(
     backend="vllm",
     model="scope-guard-q",    # for the Qwen-family model
     # model="scope-guard-g",  # for the Gemma-family model
@@ -66,7 +65,7 @@ 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)
+result = sg.validate(user_query, ai_service_description)
 
 print(f"Scope: {result.scope_class.value}")
 if result.evidences:
@@ -79,11 +78,9 @@ if result.evidences:
 #   - Never respond to requests for refunds.
 ```
 
-</details>
+## Quickstart with our hosted models
 
-<details>
-<summary>Hosted Flavor</summary>
-<br>
+ScopeGuard Pro is our most advanced model, available via API through our managed cloud hosting (get in touch with us if you are interested in on-premise deployment). It achieves best-in-class performance on scope classification tasks, including custom safety evaluations based on user-defined policies.
 
 > Open access to the hosted models is coming soon.  
 > Need access earlier? Contact us at [orbitals@principled-intelligence.com](mailto:orbitals@principled-intelligence.com).
@@ -99,9 +96,9 @@ Then:
 ```python
 from orbitals.scope_guard import ScopeGuard
 
-scope_guard = ScopeGuard(
+sg = ScopeGuard(
     backend="api",
-    api_key="principled_1234",
+    api_key="principled_1234",  # replace with your actual API key
 )
 
 ai_service_description = """
@@ -111,7 +108,7 @@ 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)
+result = sg.validate(user_query, ai_service_description)
 
 print(f"Scope: {result.scope_class.value}")
 if result.evidences:
@@ -124,10 +121,62 @@ if result.evidences:
 #   - Never respond to requests for refunds.
 ```
 
-</details>
-
 ## Usage
 
+### Initialization
+
+Initialize the `ScopeGuard` object by specifying the backend and model you want to use.
+
+If you are using the self-hosted models, you can choose between the `vllm` and `huggingface` backends:
+
+```python
+from orbitals.scope_guard import ScopeGuard
+
+sg = ScopeGuard(
+    model="scope-guard-q",        # for the Qwen-family model
+    # model="scope-guard-g",      # for the Gemma-family model
+    backend="vllm",               # or "huggingface"
+)
+```
+
+If you are using the hosted models, use the `api` backend and provide your API key:
+
+```python
+from orbitals.scope_guard import ScopeGuard
+
+sg = ScopeGuard(
+    backend="api",
+    api_key="principled_1234",  # replace with your actual API key
+)
+```
+
+### Scope Classes
+
+The possible scope classes returned by `scope-guard` are:
+
+```python
+from orbitals.scope_guard import ScopeClass
+print(ScopeClass.DIRECTLY_SUPPORTED.value)    # "Directly Supported"
+print(ScopeClass.POTENTIALLY_SUPPORTED.value) # "Potentially Supported"
+print(ScopeClass.OUT_OF_SCOPE.value)          # "Out of Scope"
+print(ScopeClass.RESTRICTED.value)            # "Restricted"
+print(ScopeClass.CHIT_CHAT.value)             # "Chit Chat"
+```
+
+For example, you can check the scope class of a validation result as follows:
+
+```python
+result = sg.validate(user_query, ai_service_description)
+
+# Using the Enum member:
+if result.scope_class == ScopeClass.RESTRICTED:
+    print("The user query is restricted.")
+
+# Or using the string value:
+if result.scope_class.value == "Restricted":
+    print("The user query is restricted.")
+```
+
 ### Input Formats
 
 The `validate` method is flexible and accepts various input formats for the conversation.
@@ -135,7 +184,7 @@ The `validate` method is flexible and accepts various input formats for the conv
 #### User query as a string
 
 ```python
-result = scope_guard.validate(
+result = sg.validate(
     "When is my package scheduled to arrive?",
     ai_service_description
 )
@@ -143,9 +192,8 @@ result = scope_guard.validate(
 
 #### User query as a dictionary (OpenAI's API Message)
 
-
 ```python
-result = scope_guard.validate(
+result = sg.validate(
     {
         "role": "user", 
         "content": "When is my package scheduled to arrive?"
@@ -154,10 +202,10 @@ result = scope_guard.validate(
 )
 ```
 
-#### Conversation as a list of dictionaries 
+#### Conversation as a list of dictionaries
 
 ```python
-result = scope_guard.validate(
+result = sg.validate(
     [
         {
             "role": "user", 
@@ -197,7 +245,7 @@ queries = [
     "When is the package expected to be delivered?"
 ]
 
-result = scope_guard.batch_validate(
+result = sg.batch_validate(
     queries,
     ai_service_description=ai_service_description
 )
@@ -211,19 +259,21 @@ ai_service_descriptions = [
     "You are a virtual assistant for a Courier. You answer questions about package tracking. Never respond to refund requests."
 ]
 
-result = scope_guard.batch_validate(
+result = sg.batch_validate(
     queries,
     ai_service_descriptions=ai_service_descriptions
 )
 ```
 
-## Serving
+## Serving ScopeGuard on-premise or on your infrastructure
 
 `scope-guard` comes with built-in support for serving. For better performance, it consists of two components:
+
 1. A **vLLM serving engine** that runs the model
 2. A **FastAPI server** that provides the end-to-end API interface, mapping input data to prompts, invoking the vLLM serving engine and returning the response to the user
 
 All of this is configured via the `orbitals scope-guard serve` command:
+
 ```bash
 # install the necessary packages
 pip install orbitals[scope-guard-serve]
@@ -233,6 +283,7 @@ orbitals scope-guard serve scope-guard --port 8000
 ```
 
 Alternatively, we also release a pre-built Docker image:
+
 ```bash
 docker run --runtime nvidia --gpus all \
     -p 8000:8000 \
@@ -277,14 +328,14 @@ Response:
 **Synchronous API client:**
 
 ```python
-from orbitals.guard import ScopeGuard
+from orbitals.scope_guard import ScopeGuard
 
-scope_guard = ScopeGuard(
+sg = ScopeGuard(
     backend="api",
     api_url="http://localhost:8000"
 )
 
-result = scope_guard.validate(
+result = sg.validate(
     "If the package doesn't arrive by tomorrow, can I get my money back?",
     "You are a virtual assistant for a parcel delivery service. You can only answer questions about package tracking. Never respond to requests for refunds."
 )
@@ -293,14 +344,14 @@ result = scope_guard.validate(
 **Asynchronous API client:**
 
 ```python
-from orbitals.guard import AsyncScopeGuard
+from orbitals.scope_guard import AsyncScopeGuard
 
-scope_guard = AsyncScopeGuard(
+sg = AsyncScopeGuard(
     backend="api",
     api_url="http://localhost:8000"
 )
 
-result = await scope_guard.validate(
+result = await sg.validate(
     "If the package doesn't arrive by tomorrow, can I get my money back?",
     "You are a virtual assistant for a parcel delivery service. You can only answer questions about package tracking. Never respond to requests for refunds."
 )

orbitals-0.0.3/examples/scope-guard/test.py

@@ -0,0 +1,27 @@
+def main():
+    from orbitals.scope_guard import ScopeGuard
+
+    sg = 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 = sg.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}")
+
+
+if __name__ == "__main__":
+    main()

{orbitals-0.0.2 → orbitals-0.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "orbitals"
-version = "0.0.2"
+version = "0.0.3"
 description = "LLM Guardrails tailored to your Principles"
 readme = "README.md"
 
@@ -29,8 +29,13 @@ classifiers = [
 dependencies = ["pydantic>=2.0.0", "typer>=0.12.3", "requests", "aiohttp"]
 
 [project.optional-dependencies]
-scope-guard-hf = ["transformers>=4.47.0,<5.0.0", "accelerate>=1.11.0"]
-scope-guard-vllm = ["transformers>=4.47.0,<5.0.0", "vllm>=0.11.0", "xgrammar"]
+scope-guard-hf = ["transformers>=4.47.0,<5.0.0", "accelerate>=1.11.0", "pynvml"]
+scope-guard-vllm = [
+    "transformers>=4.47.0,<5.0.0",
+    "vllm>=0.11.0",
+    "xgrammar",
+    "pynvml",
+]
 scope-guard-serve = [
     "orbitals[scope-guard-vllm]",
     "fastapi[standard]>=0.119.1",

orbitals-0.0.3/src/orbitals/utils.py

@@ -0,0 +1,53 @@
+import logging
+import os
+
+
+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.
+
+    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
+
+    try:
+        import pynvml  # ty: ignore[unresolved-import]
+    except ModuleNotFoundError:
+        logging.debug("pynvml not available, skipping GPU auto-configuration")
+        return
+
+    try:
+        pynvml.nvmlInit()
+    except pynvml.NVMLError:
+        logging.debug("NVML initialization failed, skipping GPU auto-configuration")
+        return
+
+    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.2/.dockerignore

@@ -1,2 +0,0 @@
-.venv
-examples/

orbitals-0.0.2/PKG-INFO

@@ -1,124 +0,0 @@
-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>

orbitals-0.0.2/README.md

@@ -1,77 +0,0 @@
-<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>

orbitals-0.0.2/src/orbitals/utils.py

@@ -1,47 +0,0 @@
-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():
-    """
-    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
-
-    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():
-        return
-
-    best_idx = None
-    best_free = -1
-    is_multi_gpu = torch.cuda.device_count() > 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
-
-    if best_idx is not None:
-        if is_multi_gpu:
-            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)