feat: build, test, and package the Python SDK standalone

.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

.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

.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

.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.

.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

.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)

.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

.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+# 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@e6a8b3978addb5a52f2b4cd9d91eafa7f0ab959d # v4.2.0
+
+      # 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@e6a8b3978addb5a52f2b4cd9d91eafa7f0ab959d # v4.2.0
+
+      - 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@e6a8b3978addb5a52f2b4cd9d91eafa7f0ab959d # v4.2.0
+
+      - name: Build, verify, and install the wheel and sdist
+        run: mise run build
+
+  # 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

.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@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+        with:
+          languages: python
+          build-mode: none
+          config: |
+            paths-ignore:
+              - src/openshell/_proto
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+        with:
+          category: /language:python