TASK-450587736: Scaffold alissa-python-sdk namespace-anchor package with tool extras

.github/workflows/check-style.yaml

@@ -0,0 +1,27 @@
+name: Check Python Style
+on: [pull_request]
+
+jobs:
+  python-style-check:
+    strategy:
+      matrix:
+        path:
+          - alissa
+    name: Python Style Check for ${{ matrix.path }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone Repo
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install Requirements
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements-develop.txt
+      - name: Execute Style Check
+        run: |
+          bash check-style.sh ${{ matrix.path }}

.github/workflows/check-tests.yaml

@@ -0,0 +1,30 @@
+name: Check Unit-Tests and Simple Coverage Report
+on: [pull_request]
+
+jobs:
+  python-unit-testing:
+    strategy:
+      matrix:
+        path:
+          - alissa
+    name: Unit-Test Check for ${{ matrix.path }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone Repo
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install Requirements
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements-develop.txt
+      - name: Install Package
+        run: python -m pip install -e ./${{ matrix.path }}
+      - name: Execute Unit-Tests
+        run: |
+          bash tests-unit.sh ${{ matrix.path }}
+          bash tests-coverage.sh ${{ matrix.path }}

.github/workflows/check-types.yaml

@@ -0,0 +1,29 @@
+name: Check Python Types
+on: [pull_request]
+
+jobs:
+  python-unit-testing:
+    strategy:
+      matrix:
+        path:
+          - alissa
+    name: Python Types Check for ${{ matrix.path }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone Repo
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install Requirements
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements-develop.txt
+      - name: Install Package
+        run: python -m pip install -e ./${{ matrix.path }}
+      - name: Execute Type Checks
+        run: |
+          bash check-types.sh ${{ matrix.path }}

.github/workflows/check-wheel.yaml

@@ -0,0 +1,34 @@
+name: Check Creation of Wheel Package
+on: [pull_request]
+
+jobs:
+  python-wheel-check:
+    strategy:
+      matrix:
+        path:
+          - alissa
+    name: Wheel Package Check for ${{ matrix.path }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone Repo
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install Requirements
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install setuptools wheel
+      - name: Create Wheel Package
+        run: (cd ${{ matrix.path }}; python setup.py bdist_wheel)
+      - name: Install Wheel Package
+        run: python -m pip install ${{ matrix.path }}/dist/*.whl
+      - name: Execute Simple Command to Verify Installation
+        run: |
+          python -c "from alissa.sdk.version import version; print(version)"
+          python -c "from alissa.sdk import installed_tools; print(installed_tools())"
+          alissa-py --help
+          alissa-py --tools

.github/workflows/package-publish.yaml

@@ -0,0 +1,50 @@
+name: Python Package Publish
+
+# Publishing is irreversible: a version number, once on PyPI, can never be
+# reused even if the release is deleted. The version file is therefore the
+# release trigger -- merging a PR that does not bump it publishes nothing,
+# and twine's --skip-existing keeps a re-run from failing the workflow.
+
+on:
+  pull_request:
+    paths:
+      - .github/workflows/package-publish.yaml
+      - alissa/**
+    types:
+      - closed
+    branches:
+      - main
+
+jobs:
+  python-publish:
+    environment: PYPI Package Publishing
+    strategy:
+      matrix:
+        path:
+          - alissa
+    if: github.event.pull_request.merged == true
+    name: Python Package Build and Publish for ${{ matrix.path }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone Repo
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install Build Tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+      - name: Build
+        run: (cd ${{ matrix.path }}; python -m build)
+      - name: Check Metadata
+        run: twine check ${{ matrix.path }}/dist/*
+      - name: Publish
+        env:
+          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+          GH_BRANCH: ${{ github.ref }}
+        run: twine upload --verbose --skip-existing ${{ matrix.path }}/dist/*

.gitignore

@@ -0,0 +1,13 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+.pytest_cache/
+.mypy_cache/
+
+# Local environments
+venv/
+.venv/

.python-version

@@ -0,0 +1 @@
+3.12.3

README.md

@@ -1,2 +1,86 @@
 # alissa-python-sdk
-Alissa Python SDK
+
+The single Python package that owns and anchors the `alissa` import namespace —
+`import alissa.sdk` — and curates its **tool extras**:
+
+```sh
+pip install alissa                               # SDK core, zero third-party deps
+pip install 'alissa[tools.github.revloop]'       # + a tool, merged into alissa.tools.*
+pip install 'alissa[all]'                        # + every tool
+```
+
+## How ownership works
+
+`alissa` is the anchor distribution: the thing you `pip install`, the top-level
+SDK surface (`alissa.sdk`), and the list of available tools (its extras). But it
+ships **no** `__init__.py` at the namespace levels, so it doesn't monopolize the
+namespace — tool distributions pulled in by extras merge their own
+`alissa.tools.*` subtrees in via [PEP 420](https://peps.python.org/pep-0420/):
+
+```
+alissa/                                  ← namespace (no __init__.py)
+├── sdk/               __init__.py        ← the SDK distribution: surface + version file
+├── utils/             __init__.py        ← the SDK distribution: shared helpers (utils.version)
+└── tools/                               ← namespace
+    └── github/
+        └── reviewloop/  __init__.py      ← ships from alissa-tools-github-reviewloop
+```
+
+Each `alissa[tools.<area>.<name>]` extra maps to a separately published
+distribution. Tools stay independently versioned and released; the SDK just
+curates which ones exist and pulls them in on demand. The mapping lives in a
+registry, so an extra name need not match its distribution name — today
+`tools.github.revloop` pulls `alissa-tools-github-reviewloop`, pending that
+package's rename. See [`alissa/README.md`](./alissa/README.md) for the full
+model and for how to add a new tool extra.
+
+## Repository layout
+
+This repo is a monorepo of distributions. Today it holds one, `alissa/`; the
+shared dev tooling and CI live at the root and matrix over each distribution's
+directory name.
+
+```
+alissa-python-sdk/
+├── alissa/                     ← the `alissa` distribution
+│   ├── setup.py                ← packaging + extras_require (the tool curation)
+│   ├── requirements.txt        ← core deps (empty — the SDK core has none)
+│   ├── MANIFEST.in
+│   └── src/
+│       ├── main/alissa/sdk/    ← owned leaf: SDK surface (+ plain-text `version` file)
+│       ├── main/alissa/utils/  ← owned leaf: shared helpers (alissa.utils.version)
+│       └── test/test_alissa/   ← mirrors main as test_*
+├── .github/workflows/          ← style / types / tests / wheel / publish (matrix: alissa)
+├── check-style.sh  check-types.sh  tests-unit.sh  tests-coverage.sh
+├── requirements-develop.txt
+└── .python-version             ← 3.12.3
+```
+
+## Develop
+
+```sh
+python -m venv venv && source venv/bin/activate
+pip install -r requirements-develop.txt
+pip install -e ./alissa
+
+alissa-py                  # SDK version + how to add tools
+alissa-py --tools          # list installed alissa.tools.* packages
+```
+
+## Checks
+
+Each script takes a distribution directory (matching the CI matrix):
+
+```sh
+bash tests-unit.sh alissa
+bash tests-coverage.sh alissa
+bash check-style.sh alissa
+bash check-types.sh alissa
+```
+
+## Publishing
+
+Publishing is driven by the per-distribution `version` file
+(`alissa/src/main/alissa/sdk/version`). Merging a PR to `main` that bumps it
+publishes to PyPI; a PR that doesn't bump it publishes nothing
+(`twine upload --skip-existing`). Versions are irreversible once on PyPI.

alissa/MANIFEST.in

@@ -0,0 +1,2 @@
+include requirements.txt
+include src/main/alissa/sdk/version