orb-py 1.2.2__tar.gz → 1.3.0__tar.gz

orb_py-1.3.0/PKG-INFO

@@ -0,0 +1,540 @@
+Metadata-Version: 2.4
+Name: orb-py
+Version: 1.3.0
+Summary: Open Resource Broker (ORB) — dynamic cloud resource provisioning via CLI and REST API
+Author-email: AWS Professional Services <aws-proserve@amazon.com>
+Maintainer-email: AWS Professional Services <aws-proserve@amazon.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/awslabs/open-resource-broker
+Project-URL: Documentation, https://awslabs.github.io/open-resource-broker/
+Project-URL: Repository, https://github.com/awslabs/open-resource-broker
+Project-URL: Bug Reports, https://github.com/awslabs/open-resource-broker/issues
+Keywords: aws,ec2,hostfactory,symphony,hpc,cluster,cloud,infrastructure
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Clustering
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3>=1.42.21
+Requires-Dist: botocore>=1.42.21
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: urllib3>=2.6.3
+Requires-Dist: PyJWT>=2.8.0
+Requires-Dist: cryptography>=46.0.5
+Requires-Dist: filelock>=3.20.1
+Requires-Dist: requests>=2.31.0
+Requires-Dist: PyYAML>=6.0.0
+Requires-Dist: jsonschema>=4.17.0
+Provides-Extra: cli
+Requires-Dist: rich>=13.3.0; extra == "cli"
+Requires-Dist: rich-argparse>=1.0.0; extra == "cli"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.128.0; extra == "api"
+Requires-Dist: starlette>=0.49.1; extra == "api"
+Requires-Dist: uvicorn>=0.24.0; extra == "api"
+Requires-Dist: jinja2>=3.1.0; extra == "api"
+Provides-Extra: monitoring
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "monitoring"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "monitoring"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == "monitoring"
+Requires-Dist: opentelemetry-instrumentation-boto>=0.41b0; extra == "monitoring"
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0; extra == "monitoring"
+Requires-Dist: prometheus-client>=0.17.0; extra == "monitoring"
+Requires-Dist: psutil>=5.9.0; extra == "monitoring"
+Provides-Extra: all
+Requires-Dist: orb-py[api,cli,monitoring]; extra == "all"
+Provides-Extra: ci
+Requires-Dist: ruff>=0.1.0; extra == "ci"
+Requires-Dist: pathspec>=0.11.0; extra == "ci"
+Requires-Dist: pyright<2.0.0,>=1.1.408; extra == "ci"
+Requires-Dist: mypy<2.0.0,>=1.6.1; extra == "ci"
+Requires-Dist: bandit<2.0.0,>=1.7.5; extra == "ci"
+Requires-Dist: bandit-sarif-formatter<2.0.0,>=1.1.1; extra == "ci"
+Requires-Dist: pytest<10.0.0,>=7.4.3; extra == "ci"
+Requires-Dist: pytest-cov<8.0.0,>=4.1.0; extra == "ci"
+Requires-Dist: pytest-env<2.0.0,>=1.1.1; extra == "ci"
+Requires-Dist: pytest-mock<4.0.0,>=3.12.0; extra == "ci"
+Requires-Dist: pytest-asyncio<2.0.0,>=0.21.1; extra == "ci"
+Requires-Dist: pytest-timeout<3.0.0,>=2.2.0; extra == "ci"
+Requires-Dist: pytest-xdist<4.0.0,>=3.3.1; extra == "ci"
+Requires-Dist: pytest-html<5.0.0,>=4.1.1; extra == "ci"
+Requires-Dist: pytest-benchmark<6.0.0,>=5.1.0; extra == "ci"
+Requires-Dist: coverage<8.0.0,>=7.3.2; extra == "ci"
+Requires-Dist: fastapi>=0.128.0; extra == "ci"
+Requires-Dist: httpx>=0.27.0; extra == "ci"
+Requires-Dist: jinja2>=3.1.0; extra == "ci"
+Requires-Dist: moto[all]<6.0.0,>=5.1.19; extra == "ci"
+Requires-Dist: responses<1.0.0,>=0.24.0; extra == "ci"
+Requires-Dist: requests-mock<2.0.0,>=1.11.0; extra == "ci"
+Requires-Dist: joserfc>=1.6.1; extra == "ci"
+Requires-Dist: werkzeug>=3.1.6; extra == "ci"
+Requires-Dist: nltk>=3.9.3; extra == "ci"
+Requires-Dist: types-PyYAML<7.0.0,>=6.0.12.12; extra == "ci"
+Requires-Dist: types-python-dateutil<3.0.0,>=2.8.19.14; extra == "ci"
+Requires-Dist: tomli<3.0.0,>=2.0.0; extra == "ci"
+Requires-Dist: safety<4.0.0,>=3.7.0; extra == "ci"
+Requires-Dist: pip-audit<3.0.0,>=2.6.1; extra == "ci"
+Requires-Dist: semgrep<2.0.0,>=1.45.0; extra == "ci"
+Requires-Dist: cyclonedx-bom<8.0.0,>=4.0.0; extra == "ci"
+Requires-Dist: peewee>=3.18.3; extra == "ci"
+Requires-Dist: marshmallow>=4.1.2; extra == "ci"
+Requires-Dist: mkdocs<2.0.0,>=1.5.0; extra == "ci"
+Requires-Dist: mkdocs-material<10.0.0,>=9.1.0; extra == "ci"
+Requires-Dist: mkdocstrings<2.0.0,>=0.22.0; extra == "ci"
+Requires-Dist: mkdocstrings-python<3.0.0,>=1.1.0; extra == "ci"
+Requires-Dist: mkdocs-gen-files<1.0.0,>=0.5.0; extra == "ci"
+Requires-Dist: mkdocs-literate-nav<1.0.0,>=0.6.0; extra == "ci"
+Requires-Dist: mkdocs-section-index<1.0.0,>=0.3.0; extra == "ci"
+Requires-Dist: mike<3.0.0,>=1.1.0; extra == "ci"
+Requires-Dist: build<2.0.0,>=1.0.3; extra == "ci"
+Requires-Dist: wheel<1.0.0,>=0.41.3; extra == "ci"
+Provides-Extra: dev
+Requires-Dist: orb-py[ci]; extra == "dev"
+Requires-Dist: virtualenv>=20.26.6; extra == "dev"
+Requires-Dist: pre-commit<5.0.0,>=3.5.0; extra == "dev"
+Requires-Dist: bump2version<2.0.0,>=1.0.1; extra == "dev"
+Requires-Dist: python-semantic-release<11.0.0,>=10.0.0; extra == "dev"
+Requires-Dist: line-profiler<6.0.0,>=4.1.1; extra == "dev"
+Requires-Dist: memory-profiler<1.0.0,>=0.61.0; extra == "dev"
+Requires-Dist: py-spy<1.0.0,>=0.3.14; extra == "dev"
+Requires-Dist: py-cpuinfo<10.0.0,>=9.0.0; extra == "dev"
+Requires-Dist: ipdb<1.0.0,>=0.13.13; extra == "dev"
+Requires-Dist: ipython<9.0.0,>=8.16.1; extra == "dev"
+Requires-Dist: radon<7.0.0,>=6.0.1; extra == "dev"
+Requires-Dist: pip-tools<8.0.0,>=7.3.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: git-changelog<3.0.0,>=2.6.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/awslabs/open-resource-broker/main/docs/assets/orb-logo-horizontal-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/awslabs/open-resource-broker/main/docs/assets/orb-logo-horizontal.svg">
+    <img alt="Open Resource Broker" src="https://raw.githubusercontent.com/awslabs/open-resource-broker/main/docs/assets/orb-logo-horizontal.svg" width="520">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>Unified API for orchestrating and provisioning compute capacity</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/orb-py/"><img src="https://img.shields.io/pypi/v/orb-py" alt="PyPI Version"></a>
+  <a href="https://pypi.org/project/orb-py/"><img src="https://img.shields.io/pypi/pyversions/orb-py" alt="Python Versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/awslabs/open-resource-broker" alt="License"></a>
+  <a href="https://github.com/awslabs/open-resource-broker/releases"><img src="https://img.shields.io/github/v/release/awslabs/open-resource-broker" alt="Latest Release"></a>
+  <a href="https://deepwiki.com/awslabs/open-resource-broker"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
+</p>
+
+---
+
+ORB is a unified API for orchestrating and provisioning compute capacity programmatically. Define what you need in a template, request it, track it, return it — through a CLI, REST API, Python SDK, or MCP server.
+
+Built for AWS today (EC2, Auto Scaling Groups, SpotFleet, EC2Fleet), with an extensible provider system for adding new cloud backends.
+
+**Provider support:**
+- **AWS** — EC2 RunInstances, EC2Fleet, SpotFleet, Auto Scaling Groups
+- **Custom** — extensible via [provider registry](docs/root/developer_guide/architecture.md)
+
+**Scheduler support:**
+- **HostFactory** — runs as an [IBM Spectrum Symphony provider plugin](#hostfactory-integration)
+- **Standalone** — direct usage without an external scheduler
+
+## Quick Start
+
+```bash
+pip install orb-py
+orb init
+orb templates generate
+```
+
+### 1. Pick a template
+
+```bash
+orb templates list
+```
+
+### 2. Request machines
+
+```bash
+orb machines request <template-id> 3
+```
+
+### 3. Check status
+
+```bash
+orb requests status <request-id>
+```
+
+### 4. Return machines when done
+
+```bash
+orb machines return <machine-id-1> <machine-id-2> ...
+```
+
+## Setup
+
+Get ORB installed and configured for your environment.
+
+<details>
+<summary>Installation</summary>
+
+### Standard install
+
+```bash
+pip install orb-py
+```
+
+### With colored CLI output
+
+```bash
+pip install "orb-py[cli]"
+```
+
+### With REST API server
+
+```bash
+pip install "orb-py[api]"
+```
+
+### With monitoring and observability
+
+```bash
+pip install "orb-py[monitoring]"
+```
+
+### Full install (all extras)
+
+```bash
+pip install "orb-py[all]"
+```
+
+Requires Python 3.10+.
+
+</details>
+
+<details>
+<summary>Configuration</summary>
+
+`orb init` creates a `config.json` in a location based on your install type (virtualenv, user install, system install, or development checkout). Override with:
+
+```bash
+export ORB_CONFIG_DIR=/path/to/config
+```
+
+| Variable | Description |
+|---|---|
+| `ORB_ROOT_DIR` | Set base directory for all subdirs (config, work, logs, health, scripts) |
+| `ORB_CONFIG_DIR` | Override config directory path (takes precedence over `ORB_ROOT_DIR`) |
+| `ORB_WORK_DIR` | Override work directory path (takes precedence over `ORB_ROOT_DIR`) |
+| `ORB_LOG_DIR` | Override logs directory path (takes precedence over `ORB_ROOT_DIR`) |
+| `ORB_HEALTH_DIR` | Override health directory path (takes precedence over `ORB_ROOT_DIR`) |
+| `ORB_LOG_LEVEL` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+
+See the [Configuration Guide](docs/root/user_guide/configuration.md) for path resolution details, environment variables, and REST API server setup.
+
+</details>
+
+<details>
+<summary>AWS Provider Setup</summary>
+
+ORB uses boto3's standard credential chain — any method that works with the AWS CLI works with ORB.
+
+```bash
+# Verify your credentials are active
+aws sts get-caller-identity
+```
+
+**Supported credential methods:** AWS CLI profiles, environment variables (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`), IAM instance profiles, SSO (`aws sso login`), and credential process.
+
+### Supported resource types
+
+| Type | Description |
+|---|---|
+| `RunInstances` | Direct EC2 instance provisioning |
+| `EC2Fleet` | Fleet provisioning with mixed instance types |
+| `SpotFleet` | Cost-optimized spot instance fleets |
+| `AutoScalingGroup` | Managed scaling groups |
+
+See the [AWS Provider Guide](docs/root/user_guide/configuration.md) for required IAM permissions and SpotFleet service-linked role setup.
+
+</details>
+
+## Interfaces
+
+ORB provides four ways to interact with your infrastructure.
+
+<details>
+<summary>CLI Reference</summary>
+
+All available commands and flags.
+
+| Command | Description |
+|---|---|
+| `orb init` | Initialize config and discover AWS infrastructure |
+| `orb init --non-interactive` | Initialize without interactive prompts |
+| `orb templates generate` | Generate example templates for your provider |
+| `orb templates list` | List available templates |
+| `orb templates list --format table` | Table view |
+| `orb templates show <template-id>` | Show a single template |
+| `orb templates validate --file <file>` | Validate a template file |
+| `orb machines request <template-id> <n>` | Request n machines |
+| `orb machines list` | List active machines |
+| `orb machines return <machine-id> [...]` | Return one or more machines |
+| `orb requests status <request-id>` | Check request status |
+| `orb requests list` | List all requests |
+| `orb infrastructure show` | Show configured infrastructure |
+| `orb infrastructure discover` | Scan AWS for VPCs, subnets, security groups |
+| `orb infrastructure validate` | Verify infrastructure still exists in AWS |
+| `orb config show` | Show current configuration |
+| `orb config validate` | Validate configuration |
+| `orb providers list` | List configured providers |
+| `orb system health` | System health check |
+| `orb system health --detailed` | Detailed health check |
+
+Request status values: `pending`, `in_progress`, `completed`, `failed`, `cancelled`, `partial`, `timeout`.
+
+See the [CLI Reference](docs/root/cli/cli-reference.md) for the full flag reference.
+
+</details>
+
+<details>
+<summary>REST API</summary>
+
+Example API calls. Requires `pip install "orb-py[api]"` and `orb system serve`.
+
+```bash
+# Get available templates
+curl -X GET "http://localhost:8000/api/v1/templates"
+
+# Create machine request
+curl -X POST "http://localhost:8000/api/v1/requests" \
+  -H "Content-Type: application/json" \
+  -d '{"templateId": "my-template", "maxNumber": 5}'
+
+# Check request status
+curl -X GET "http://localhost:8000/api/v1/requests/req-12345"
+```
+
+</details>
+
+<details>
+<summary>Python SDK</summary>
+
+Async-first programmatic access via `ORBClient`.
+
+```python
+from orb import ORBClient as orb
+
+async with orb(provider="aws") as sdk:
+    # List templates
+    templates = await sdk.list_templates(active_only=True)
+
+    # Request machines
+    request = await sdk.request_machines(
+        template_id=templates[0]["template_id"],
+        count=3
+    )
+
+    # Check status
+    status = await sdk.get_request_status(request_id=request["created_request_id"])
+```
+
+See the [SDK Quickstart](docs/root/sdk/quickstart.md) for the full guide.
+
+</details>
+
+<details>
+<summary>MCP Server (AI Assistant Integration)</summary>
+
+ORB provides a Model Context Protocol (MCP) server for AI assistant integration:
+
+```bash
+# Start MCP server in stdio mode (for AI assistants)
+orb mcp serve --stdio
+
+# Start as TCP server (for development/testing)
+orb mcp serve --port 3000 --host localhost
+```
+
+**Available MCP Tools:**
+- Provider Management: `check_provider_health`, `list_providers`, `get_provider_config`
+- Template Operations: `list_templates`, `get_template`, `validate_template`
+- Infrastructure Requests: `request_machines`, `get_request_status`, `return_machines`
+
+**Available MCP Resources:**
+- `templates://` — Available compute templates
+- `requests://` — Provisioning requests
+- `machines://` — Compute instances
+- `providers://` — Cloud providers
+
+**Claude Desktop Configuration:**
+```json
+{
+  "mcpServers": {
+    "open-resource-broker": {
+      "command": "orb",
+      "args": ["mcp", "serve", "--stdio"]
+    }
+  }
+}
+```
+
+</details>
+
+## Integrations
+
+Connect ORB to schedulers and container platforms.
+
+<details>
+<summary>HostFactory Integration</summary>
+
+ORB integrates with IBM Spectrum Symphony as a HostFactory provider plugin, providing full API compatibility through shell scripts:
+
+| Script | Description |
+|---|---|
+| `getAvailableTemplates.sh` | List available compute templates |
+| `requestMachines.sh` | Request new compute instances |
+| `getRequestStatus.sh` | Poll request status |
+| `requestReturnMachines.sh` | Return instances |
+| `getReturnRequests.sh` | Check return request status |
+
+Scripts are available for both Linux (bash) and Windows (bat). They are generated automatically by `orb init` and placed in your config directory.
+
+**Key features:**
+- Full HostFactory API compatibility
+- Automatic CPU and RAM attribute generation from AWS instance types
+- Native HostFactory output format (camelCase JSON)
+- Drop-in replacement for existing provider plugins
+
+Example template output:
+
+```json
+{
+  "templates": [
+    {
+      "templateId": "t3-medium-template",
+      "maxNumber": 5,
+      "attributes": {
+        "type": ["String", "X86_64"],
+        "ncpus": ["Numeric", "2"],
+        "nram": ["Numeric", "4096"]
+      }
+    }
+  ]
+}
+```
+
+See the [HostFactory Guide](docs/root/hostfactory/integration_guide.md) for full integration details.
+
+</details>
+
+<details>
+<summary>Docker Deployment</summary>
+
+Run ORB as a containerized service.
+
+```bash
+git clone https://github.com/awslabs/open-resource-broker.git
+cd open-resource-broker
+cp .env.example .env
+# Edit .env with your configuration
+docker-compose up -d
+curl http://localhost:8000/health
+```
+
+</details>
+
+## Project
+
+Architecture, development, and documentation.
+
+<details>
+<summary>Architecture</summary>
+
+ORB is built on Clean Architecture with Domain-Driven Design (DDD) and CQRS:
+
+- **Domain layer** — pure business logic, no infrastructure dependencies
+- **Application layer** — command/query handlers using abstract ports
+- **Infrastructure layer** — AWS adapters, DI container, storage strategies
+- **Interface layer** — CLI, REST API, MCP server
+
+The **provider system** uses a Strategy/Registry pattern — each cloud provider (AWS, future providers) registers its own strategy, handlers, and template format. The **scheduler system** uses the same pattern — HostFactory and Default schedulers are interchangeable strategies behind a common port.
+
+See the [Architecture Guide](docs/root/developer_guide/architecture.md) for details.
+
+</details>
+
+<details>
+<summary>Development</summary>
+
+Set up a local development environment.
+
+```bash
+git clone https://github.com/awslabs/open-resource-broker.git
+cd open-resource-broker
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Run the test suite:
+
+```bash
+make test
+```
+
+Lint and format:
+
+```bash
+make lint
+make format
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.
+
+</details>
+
+<details>
+<summary>Documentation & CI</summary>
+
+[![Test Matrix](https://github.com/awslabs/open-resource-broker/workflows/Test%20Matrix/badge.svg)](https://github.com/awslabs/open-resource-broker/actions/workflows/test-matrix.yml)
+[![Quality Checks](https://github.com/awslabs/open-resource-broker/workflows/Quality%20Checks/badge.svg)](https://github.com/awslabs/open-resource-broker/actions/workflows/ci-quality.yml)
+[![Security Scanning](https://github.com/awslabs/open-resource-broker/workflows/Security%20Scanning/badge.svg)](https://github.com/awslabs/open-resource-broker/actions/workflows/security-code.yml)
+
+- [Quick Start](docs/root/getting_started/quick_start.md)
+- [CLI Reference](docs/root/cli/cli-reference.md)
+- [Configuration Guide](docs/root/user_guide/configuration.md)
+- [Template Management](docs/root/user_guide/templates.md)
+- [Troubleshooting](docs/root/user_guide/troubleshooting.md)
+- [Architecture](docs/root/developer_guide/architecture.md)
+- [API Reference](docs/root/api/readme.md)
+- [Deployment](docs/root/deployment/readme.md)
+- [DeepWiki](https://deepwiki.com/awslabs/open-resource-broker) — AI-generated codebase documentation
+
+Full docs: [awslabs.github.io/open-resource-broker](https://awslabs.github.io/open-resource-broker/)
+
+</details>
+
+---
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for responsible disclosure procedures.