orbitals 0.1.0__tar.gz → 0.1.2__tar.gz

orbitals-0.1.2/.dockerignore

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

orbitals-0.1.2/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.1.2/Dockerfile

@@ -0,0 +1,23 @@
+FROM vllm/vllm-openai:v0.14.1
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+COPY --from=ghcr.io/astral-sh/uv:0.9.8-debian-slim /usr/local/bin/uv /usr/local/bin/uvx /bin/
+
+WORKDIR /app
+ENV PATH="/app/.venv/bin:$PATH"
+ENV UV_COMPILE_BYTECODE=1
+
+ARG MODEL
+ENV MODEL=${MODEL}
+
+RUN hf download ${MODEL}
+
+COPY pyproject.toml uv.lock README.md src /app/src/
+
+RUN pip install -e .[serving]
+
+EXPOSE 8000
+
+ENTRYPOINT ["/bin/bash", "-c"]
+CMD ["orbitals scope-guard serve ${MODEL} --port 8000 --host 0.0.0.0"]

orbitals-0.1.0/Dockerfile → orbitals-0.1.2/Dockerfile copy

@@ -1,7 +1,6 @@
-FROM vllm/vllm-openai:v0.11.2 as builder
+FROM nvidia/cuda:13.1.1-cudnn-devel-ubuntu24.04 AS builder
 
 ARG DEBIAN_FRONTEND=noninteractive
-ARG MODEL
 
 COPY --from=ghcr.io/astral-sh/uv:0.9.8-debian-slim /usr/local/bin/uv /usr/local/bin/uvx /bin/
 
@@ -11,33 +10,34 @@ ENV UV_COMPILE_BYTECODE=1
 
 RUN \
     apt-get update && \
-    apt-get install -y --no-install-recommends git
+    apt-get install -y --no-install-recommends git python3.12
 
 COPY pyproject.toml uv.lock README.md /app/
 
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv venv -p 3.12 && \
-    uv sync --frozen --extra serve --no-install-project --no-dev
+    uv sync --frozen --extra scope-guard-serve --no-install-project --no-dev
 
-COPY src /app/src/
+ARG MODEL
+RUN hf download ${MODEL}
 
-RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --locked --extra serve --no-editable --no-dev
+COPY src /app/src/
 
 RUN --mount=type=cache,target=/root/.cache/uv \
-    --mount=type=secret,id=HF_TOKEN \
-    hf auth login --token $(cat /run/secrets/HF_TOKEN) && \
-    hf download $(scope-classifier convert-default-model-name ${MODEL}) && \
-    rm -rf /root/.huggingface
+    uv sync --locked --extra scope-guard-serve --no-editable --no-dev
 
 # TODO remove next line
 ENTRYPOINT ["/bin/bash", "-c"]
 
-FROM vllm/vllm-openai:v0.11.2 as runner
+FROM nvidia/cuda:13.1.1-cudnn-runtime-ubuntu24.04 AS runner
 
 WORKDIR /app
 ENV PATH="/app/.venv/bin:$PATH"
 
+RUN \
+    apt-get update && \
+    apt-get install -y --no-install-recommends python3.12
+
 COPY --from=builder /app/.venv/ /app/.venv/
 
 RUN mkdir -p /root/.cache/huggingface/hub
@@ -45,5 +45,8 @@ COPY --from=builder /root/.cache/huggingface/hub /root/.cache/huggingface/hub
 
 EXPOSE 8000
 
+ARG MODEL
+ENV MODEL=${MODEL}
+
 ENTRYPOINT ["/bin/bash", "-c"]
-CMD [ "scope-classifier", "serve", "${MODEL}", "--backend", "hf", "--port", "8000", "--host", "0.0.0.0" ]
+CMD ["orbitals scope-guard serve ${MODEL} --port 8000 --host 0.0.0.0"]

{orbitals-0.1.0 → orbitals-0.1.2}/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.1.2/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: orbitals
+Version: 0.1.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: nvidia-ml-py; 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: nvidia-ml-py; 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: nvidia-ml-py; 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: nvidia-ml-py; 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: nvidia-ml-py; 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'
+Provides-Extra: serving
+Requires-Dist: fastapi[standard]>=0.119.1; extra == 'serving'
+Requires-Dist: uvicorn>=0.29.0; extra == 'serving'
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <img src="https://raw.githubusercontent.com/Principled-Intelligence/orbitals/refs/heads/main/assets/orbitals-banner.png" width="70%" />
+    <h3 align="center">
+        <p>
+            <b>LLM Guardrails tailored to your Principles</b>
+        </p>
+    </h4>
+</div>
+
+<p align="center">
+    <a href="https://pypi.org/project/orbitals/">
+        <img src="https://img.shields.io/pypi/v/orbitals?color=green" alt="PyPI Version">
+    </a>
+    <!-- <img src="https://img.shields.io/badge/type%20checked-ty-blue.svg?color=green" alt="Type Checked with ty"> -->
+    <a href="https://pypi.org/project/orbitals/">
+        <img src="https://img.shields.io/pypi/pyversions/orbitals" alt="Python Versions">
+    </a>
+    <a href="https://raw.githubusercontent.com/Principled-Intelligence/orbitals/refs/heads/main/LICENSE">
+        <img src="https://img.shields.io/github/license/principled-intelligence/orbitals" alt="GitHub License">
+    </a>
+</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.1.2/README.md

@@ -0,0 +1,115 @@
+<div align="center">
+    <img src="https://raw.githubusercontent.com/Principled-Intelligence/orbitals/refs/heads/main/assets/orbitals-banner.png" width="70%" />
+    <h3 align="center">
+        <p>
+            <b>LLM Guardrails tailored to your Principles</b>
+        </p>
+    </h4>
+</div>
+
+<p align="center">
+    <a href="https://pypi.org/project/orbitals/">
+        <img src="https://img.shields.io/pypi/v/orbitals?color=green" alt="PyPI Version">
+    </a>
+    <!-- <img src="https://img.shields.io/badge/type%20checked-ty-blue.svg?color=green" alt="Type Checked with ty"> -->
+    <a href="https://pypi.org/project/orbitals/">
+        <img src="https://img.shields.io/pypi/pyversions/orbitals" alt="Python Versions">
+    </a>
+    <a href="https://raw.githubusercontent.com/Principled-Intelligence/orbitals/refs/heads/main/LICENSE">
+        <img src="https://img.shields.io/github/license/principled-intelligence/orbitals" alt="GitHub License">
+    </a>
+</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>