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

[RHDZMOTA]

Scaffolds the alissa-python-sdk repository for TASK-450587736, using alissa-github-review-daemon as the structural reference.

What this is

The alissa distribution: the single package that anchors the alissa import namespace and curates optional tool extras.

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 curated tool

Design decisions

• Aggregator / meta-package, not a monolith. Ships only the owned leaves alissa.sdk and alissa.utils; every namespace level (alissa, alissa.tools, ...) stays PEP 420 (no __init__.py) so separately-published tool distributions merge their alissa.tools.* subtrees into the namespace.
• Single source of truth for extras. alissa/src/main/alissa/sdk/_tools.py::CURATED_TOOLS is read by both setup.py (extras_require) and the runtime installed_tools(), so they cannot drift. It also decouples the public extra name from the distribution name.
• Discovery via the import machinery. installed_tools() probes curated tools with importlib.util.find_spec (correct for both editable and wheel installs) rather than pkgutil.walk_packages, which silently misses editable installs whose __path__ entries are synthetic finder hooks.
• Console script alissa-py. Not alissa (the Alissa by Fahera CLI), and not a literal alissa.py -- a bin/alissa.py script file would shadow the importable alissa package and break its own import.
• Shared alissa.utils.version. The version-file loader is factored out so every alissa.* distribution reuses one implementation. alissa.sdk.version dogfoods it. Downstream tools should install_requires=["alissa"]; there is no dependency cycle (base alissa requires nothing; the alissa[tools.*] extras are a separate opt-in edge) and no circular import (the SDK core never imports tool code).

Naming note

The extra is tools.github.revloop, but the distribution and module remain alissa-tools-github-reviewloop / alissa.tools.github.reviewloop -- that is what is published on PyPI (alissa-tools-github-revloop is a 404). The source package will be renamed to revloop later, to pair with a planned devloop; only the registry entry changes then.

Layout / conventions (mirrors the reference repo)

• Monorepo-of-distributions; one distribution today (alissa/).
• src/main + src/test, plain-text version file, MANIFEST.in.
• Dev scripts: check-style.sh, check-types.sh, tests-unit.sh, tests-coverage.sh.
• CI matrixed over the distribution dir: style, tests, types, wheel, publish.

Verification (local, all green)

Check	Result
tests-unit.sh alissa	11 passed
tests-coverage.sh alissa	100% (60 statements)
check-style.sh alissa (pycodestyle)	clean
check-types.sh alissa (mypy)	no issues, 9 source files
python -m build + twine check	wheel + sdist PASSED

Behavioural checks:

• pip install -e ./alissa -> import alissa.sdk exposes __version__ matching the version file; alissa-py --version -> alissa 0.1.0.
• installed_tools() -> ['alissa.tools.github.reviewloop'] with the tool installed (editable), [] in a clean env.
• Package metadata: Provides-Extra: tools-github-revloop requiring alissa-tools-github-reviewloop.
• Wheel ships alissa/sdk/* + alissa/utils/* with no alissa/__init__.py (PEP 420 intact).

Generated with Claude Code