openshell 0.0.0a0__tar.gz → 0.1.8__tar.gz

openshell-0.1.8/.gitattributes

@@ -0,0 +1,7 @@
+# Generated protobuf bindings (committed; see README). GitHub collapses them
+# in diffs and leaves them out of language statistics. _proto/__init__.py is
+# hand-written and stays visible.
+src/openshell/_proto/*_pb2.py linguist-generated
+src/openshell/_proto/*_pb2.pyi linguist-generated
+src/openshell/_proto/*_pb2_grpc.py linguist-generated
+src/openshell/_proto/*_pb2_grpc.pyi linguist-generated

openshell-0.1.8/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# The sdk team owns the SDK; OpenShell maintainers review as a fallback.
+# An infra review for CI and the release scripts comes back with #15.
+* @ai-openshell/sdk @ai-openshell/maintainers

openshell-0.1.8/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: Apache-2.0
+
+name: Bug Report
+description: Report unexpected behavior of the Python SDK with a clear user story and expected outcome.
+type: Bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Bug Reports
+
+        Describe who encountered the bug, the problem it creates, why it matters, and the observable criteria for a fix. Please check the latest `openshell` release on PyPI and search existing issues for possible duplicates before filing.
+
+        Problems with the gateway, CLI, or sandboxes belong in [NVIDIA/OpenShell](https://github.com/NVIDIA/OpenShell/issues). Do not report security vulnerabilities here; follow [SECURITY.md](https://github.com/ai-openshell/sdk-python/blob/main/SECURITY.md) instead.
+
+  - type: textarea
+    id: user-story
+    attributes:
+      label: User Story
+      description: Describe the specific use case and behavior you directly encountered or need.
+      placeholder: |
+        I use the OpenShell Python SDK for <specific use case>.
+        I directly encountered or need <specific behavior>.
+        This affects <outcome>.
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: Summarize what is broken in the SDK's current behavior. Describe its consequences and current workarounds in Impact / Why This Matters.
+      placeholder: Describe the gap or failure in the SDK's current behavior and when it occurs.
+    validations:
+      required: true
+
+  - type: textarea
+    id: impact
+    attributes:
+      label: Impact / Why This Matters
+      description: |
+        Explain how the bug affects users and what they must do to work around it today. Include evidence where available, but do not diagnose the cause or prescribe the fix.
+      placeholder: |
+        When this happens, users must...
+        This results in...
+        This matters because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance Criteria
+      description: List the specific, observable outcomes that would demonstrate the bug is fixed.
+      placeholder: |
+        - [ ] <observable outcome>
+        - [ ] <observable outcome>
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction Steps
+      description: Provide a minimal Python snippet against an OpenShell gateway, and what you expected instead.
+      placeholder: |
+        from openshell import Sandbox
+
+        with Sandbox(...) as sb:
+            ...
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include the SDK, Python, and gateway versions.
+      placeholder: |
+        - openshell (SDK): 0.x.x (output of `python -c "import openshell; print(openshell.__version__)"`)
+        - Python: 3.x.x
+        - OpenShell gateway: v0.x.x, deployment mode and compute driver
+        - OS: macOS 15.2 / Ubuntu 24.04 / Windows 11 + WSL2
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: |
+        Include the smallest relevant traceback, error message, or log excerpt.
+        Redact credentials, API keys, tokens, and query parameters before pasting.
+      render: shell
+    validations:
+      required: false

openshell-0.1.8/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: Apache-2.0
+
+blank_issues_enabled: false
+contact_links:
+  - name: Gateway, CLI, or sandbox problem?
+    url: https://github.com/NVIDIA/OpenShell/issues/new/choose
+    about: >
+      This repository is the Python SDK only. Report problems with the
+      OpenShell gateway, CLI, sandboxes, or the gRPC API in NVIDIA/OpenShell.
+  - name: Security vulnerability?
+    url: https://github.com/ai-openshell/sdk-python/blob/main/SECURITY.md
+    about: >
+      Do not report security vulnerabilities through GitHub issues. Follow
+      SECURITY.md and use the private reporting form.

openshell-0.1.8/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+
+name: Feature Request
+description: Propose an SDK feature with a user story and API design. Not a "please build this" request.
+type: Feature
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Design-First Feature Proposals
+
+        Describe who needs the feature, the problem it solves, why the current gap matters, the API you would like to use, and the observable criteria for success. Leave implementation choices to the people building the feature.
+
+        The SDK wraps the OpenShell gateway's API. A feature that needs a new gateway capability starts in [NVIDIA/OpenShell](https://github.com/NVIDIA/OpenShell/issues); link that issue here.
+
+  - type: textarea
+    id: user-story
+    attributes:
+      label: User Story
+      description: Describe the specific use case and behavior you directly encountered or need.
+      placeholder: |
+        I use the OpenShell Python SDK for <specific use case>.
+        I directly encountered or need <specific behavior>.
+        This affects <outcome>.
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: Summarize the capability missing from the SDK today. Describe its consequences and current workarounds in Impact / Why This Matters.
+    validations:
+      required: true
+
+  - type: textarea
+    id: impact
+    attributes:
+      label: Impact / Why This Matters
+      description: |
+        Explain what users must do today and why that is insufficient, for example calling `openshell._proto` stubs directly. Include concrete evidence where available, but do not prescribe the implementation.
+      placeholder: |
+        Without this feature, users must...
+        This results in...
+        This matters because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: design
+    attributes:
+      label: Proposed API
+      description: |
+        How should this look to an SDK user? Show a notional Python example and describe the externally observable behavior.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance Criteria
+      description: List specific, observable outcomes that would make this feature complete without prescribing how implementers achieve them.
+      placeholder: |
+        - [ ] <observable outcome>
+        - [ ] <observable outcome>
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Explain what you tried with the current SDK, including the generated `openshell._proto` stubs, and why the proposal serves your use case better.
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I've reviewed existing issues and the README
+          required: true
+        - label: This is a design proposal, not a "please build this" request
+          required: true

openshell-0.1.8/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Summary
+<!-- 1-3 sentences: what this PR does and why -->
+
+## Related Issue
+<!-- Closes #NNN. Small fixes, dependency updates and core bump PRs may skip the issue; say why instead. -->
+
+## Changes
+<!-- Bullet list of key changes. Call out changes to the public API (`openshell.__all__`) or to `openshell._proto`. -->
+
+## Testing
+<!-- Report the verification you ran for this change. -->
+- [ ] `mise run ci` passes
+- [ ] Unit tests added/updated (if applicable)
+- [ ] E2E tests added/updated (if applicable)
+
+## Checklist
+
+- [ ] Follows [Conventional Commits](https://www.conventionalcommits.org/)
+- [ ] Commits are signed off (DCO)
+- [ ] README or CONTRIBUTING.md updated (if applicable)

openshell-0.1.8/.github/dependabot.yml

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: Apache-2.0
+
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+    groups:
+      python-minor-and-patch:
+        update-types: ["minor", "patch"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    cooldown:
+      default-days: 7

openshell-0.1.8/.github/workflows/ci.yml

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  checks:
+    name: checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
+
+      # fetch-core.sh reads proto/ and sdk/conformance from NVIDIA/OpenShell
+      # at the pinned ref (public, no credentials).
+      - name: Format, lint, typecheck, proto and fixture drift
+        run: mise run check
+
+  test:
+    name: test (${{ matrix.python }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # Keep in sync with requires-python and the classifiers in pyproject.toml.
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    env:
+      UV_PYTHON: ${{ matrix.python }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
+
+      - name: Unit tests
+        run: mise run test
+
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          # setuptools-scm reads the version from git history.
+          fetch-depth: 0
+
+      - uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
+
+      - name: Build, verify, and install the wheel and sdist
+        run: mise run build
+
+  e2e:
+    name: e2e
+    uses: ./.github/workflows/e2e.yml
+
+  # The one required status check. Its name matches ai-openshell/sdk-go, so
+  # rulesets can require `ci` in every SDK repository regardless of the jobs
+  # each one runs.
+  ci:
+    name: ci
+    if: always()
+    needs: [checks, test, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require every job to succeed
+        env:
+          RESULTS: ${{ join(needs.*.result, ' ') }}
+        run: |
+          for result in $RESULTS; do
+            if [ "$result" != success ]; then
+              echo "::error::a required job finished with '$result' ($RESULTS)"
+              exit 1
+            fi
+          done

openshell-0.1.8/.github/workflows/codeql.yml

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+
+name: CodeQL
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "29 5 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  analyze:
+    name: CodeQL (python)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # Python needs no build. The generated bindings are left out.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
+        with:
+          languages: python
+          build-mode: none
+          config: |
+            paths-ignore:
+              - src/openshell/_proto
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
+        with:
+          category: /language:python

openshell-0.1.8/.github/workflows/core-drift.yml

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Nightly comparison of core main with the pinned core tag; keeps the single
+# "Core main drift" issue current (mise run core:drift).
+name: core-drift
+
+on:
+  schedule:
+    - cron: "41 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: core-drift
+  cancel-in-progress: false
+
+jobs:
+  drift:
+    name: drift
+    # The bot secrets live in the sdk-bot environment, which only main can
+    # deploy to, so a pushed branch can't mint a bot token.
+    environment: sdk-bot
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - id: app-token
+        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
+        with:
+          client-id: ${{ secrets.SDK_BOT_CLIENT_ID }}
+          private-key: ${{ secrets.SDK_BOT_PRIVATE_KEY }}
+          permission-issues: write
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
+
+      # Exit 1 with a report means drift; the issue records it. No report
+      # means the check itself broke, which the failure step records.
+      - name: Check drift against core main
+        run: |
+          mise run core:drift -- --out drift-report.md || true
+          test -s drift-report.md
+          cat drift-report.md >>"$GITHUB_STEP_SUMMARY"
+
+      - name: Update the drift issue
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: mise run core:drift-issue -- drift-report.md
+
+      - name: Report failure
+        if: failure()
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: mise run core:report-failure -- core-drift "$RUN_URL"

openshell-0.1.8/.github/workflows/core-watch.yml

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Opens one update proposal per new core release tag
+# (mise run core:bump).
+name: core-watch
+
+on:
+  schedule:
+    - cron: "17 * * * *"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Core tag to propose (vX.Y.Z or vX.Y.Z-pre.N); empty proposes every new tag
+        required: false
+        default: ""
+
+permissions:
+  contents: read
+
+concurrency:
+  group: core-watch
+  cancel-in-progress: false
+
+jobs:
+  watch:
+    name: watch
+    # The bot secrets live in the sdk-bot environment, which only main can
+    # deploy to, so a pushed branch can't mint a bot token.
+    environment: sdk-bot
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - id: app-token
+        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
+        with:
+          client-id: ${{ secrets.SDK_BOT_CLIENT_ID }}
+          private-key: ${{ secrets.SDK_BOT_PRIVATE_KEY }}
+          permission-contents: write
+          permission-pull-requests: write
+          permission-issues: write
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
+          persist-credentials: true
+
+      - uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
+
+      - name: Set the bot identity
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
+        run: |
+          set -euo pipefail
+          id=$(gh api "users/${APP_SLUG}[bot]" --jq .id)
+          git config user.name "${APP_SLUG}[bot]"
+          git config user.email "${id}+${APP_SLUG}[bot]@users.noreply.github.com"
+
+      - name: Propose new core tags
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          if [ -n "$INPUT_TAG" ]; then
+            tags=$INPUT_TAG
+          else
+            tags=$(mise run --quiet core:tags)
+          fi
+          if [ -z "$tags" ]; then
+            echo "No core tags newer than $(mise run --quiet core:version)."
+            exit 0
+          fi
+          for t in $tags; do
+            mise run core:bump -- "$t"
+          done
+
+      - name: Report failure
+        if: failure()
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: mise run core:report-failure -- core-watch "$RUN_URL"

openshell-0.1.8/.github/workflows/e2e.yml

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Runs the E2E suite against the published gateway of a core version, started
+# from core's deploy/docker files (scripts/e2e/start-gateway.sh). Sandboxes
+# run the image from tests/e2e/Dockerfile.workload, which has the same Python
+# as the client, so exec_python can unpickle what the client pickled.
+name: e2e
+
+on:
+  workflow_call:
+    inputs:
+      core-version:
+        description: Core version (default the pin, OPENSHELL_CORE_REF in mise.toml)
+        type: string
+        default: ""
+  workflow_dispatch:
+    inputs:
+      core-version:
+        description: Core version, for example v0.1.7 (default the pin, OPENSHELL_CORE_REF in mise.toml)
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+jobs:
+  e2e:
+    name: e2e
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: jdx/mise-action@f5be966e4a917d54244728e6a5fdcd1d93a35e6c # v5.2.6
+
+      - name: Build the sandbox image
+        run: mise run e2e:image
+
+      - name: Start the gateway
+        env:
+          CORE_VERSION: ${{ inputs.core-version }}
+        run: |
+          set -euo pipefail
+          version=${CORE_VERSION:-$(mise run -q core:version)}
+          echo "Core version: $version" >>"$GITHUB_STEP_SUMMARY"
+          scripts/e2e/start-gateway.sh "$version" --default-image openshell/e2e-python:dev
+
+      - name: Run the E2E suite
+        env:
+          OPENSHELL_GATEWAY: e2e
+        run: mise run e2e
+
+      - name: Stop the gateway
+        if: always()
+        run: scripts/e2e/stop-gateway.sh
+
+      - name: Upload the gateway log
+        if: failure()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: gateway-log
+          path: ${{ runner.temp }}/openshell-e2e/gateway.log
+          if-no-files-found: ignore