feat(package): expose swarms.__version__ (kyegomez#2129)

`import swarms; swarms.__version__` raised AttributeError. The package
defined no `__version__` and no module `__getattr__`, so the attribute
every Python package is expected to carry simply was not there.

This is not only a docs problem. scripts/docker/test_docker.py reads
swarms.__version__ twice as its smoke test, catches the AttributeError
in a bare `except Exception`, and reports "Tests failed! Please check
the Docker image" on a perfectly good install. The command documented
in scripts/docker/DOCKER.md fails the same way.

The version is read from the installed distribution's metadata rather
than duplicated as a literal, so it cannot drift from the version in
pyproject.toml the way a hand-maintained string does.

Resolution is deferred to first access through a module `__getattr__`,
then cached in globals(). importlib.metadata.version() scans dist-info
and costs ~0.44ms, which is not worth adding to every `import swarms`
for an attribute most programs never read. A `__dir__` is included so
the name is still discoverable before anything has touched it, which
is what kyegomez#196 originally asked for.

A source checkout with no installed distribution has no metadata to
read and reports "unknown" rather than raising, so the attribute is
safe to reference unconditionally.

Tests: 8 in tests/test___init__.py, which was an empty file. 7 fail
against master.

Author: kyegomez

swarms/__init__.py

@@ -14,3 +14,36 @@
 from swarms.telemetry import *  # noqa: E402, F403
 from swarms.tools import *  # noqa: E402, F403
 from swarms.utils import *  # noqa: E402, F403
+
+
+def __getattr__(name: str) -> str:
+    """Resolve ``swarms.__version__`` on first access.
+
+    The version comes from the installed distribution's metadata rather
+    than a literal here, so it cannot drift from ``pyproject.toml``.
+    Resolving it lazily keeps the dist-info scan off the import path for
+    the majority of programs, which never read it.
+    """
+    if name == "__version__":
+        from importlib.metadata import (
+            PackageNotFoundError,
+            version,
+        )
+
+        try:
+            resolved = version("swarms")
+        except PackageNotFoundError:
+            # A source checkout with no installed distribution.
+            resolved = "unknown"
+
+        globals()["__version__"] = resolved
+        return resolved
+
+    raise AttributeError(
+        f"module {__name__!r} has no attribute {name!r}"
+    )
+
+
+def __dir__() -> list:
+    """Advertise ``__version__`` before anything has accessed it."""
+    return sorted(set(globals()) | {"__version__"})

tests/test___init__.py

@@ -0,0 +1,77 @@
+import re
+import subprocess
+import sys
+from importlib.metadata import PackageNotFoundError
+
+import pytest
+
+import swarms
+
+
+def test_version_attribute_exists():
+    assert isinstance(swarms.__version__, str)
+    assert swarms.__version__
+
+
+def test_version_matches_installed_distribution():
+    from importlib.metadata import version
+
+    assert swarms.__version__ == version("swarms")
+
+
+def test_version_is_pep440_shaped():
+    assert re.match(
+        r"^\d+\.\d+", swarms.__version__
+    ), f"expected a numeric version, got {swarms.__version__!r}"
+
+
+def test_hasattr_reports_true():
+    assert hasattr(swarms, "__version__")
+
+
+def test_version_is_advertised_by_dir_before_access():
+    """dir() lists it even in a process that has never read it."""
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            "import swarms; print('__version__' in dir(swarms))",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert result.stdout.strip().endswith("True"), result.stderr
+
+
+def test_unknown_attribute_still_raises_attribute_error():
+    with pytest.raises(AttributeError) as excinfo:
+        swarms.definitely_not_a_real_attribute
+
+    assert "definitely_not_a_real_attribute" in str(excinfo.value)
+
+
+def test_version_is_cached_after_first_access():
+    """The second read comes from globals(), not a fresh metadata scan."""
+    swarms.__version__
+    assert "__version__" in vars(swarms)
+
+
+def test_falls_back_when_distribution_is_absent(monkeypatch):
+    """A source checkout with no installed dist reports 'unknown'."""
+    import importlib.metadata as metadata
+
+    monkeypatch.delitem(vars(swarms), "__version__", raising=False)
+
+    def _raise(name):
+        raise PackageNotFoundError(name)
+
+    monkeypatch.setattr(metadata, "version", _raise)
+
+    assert swarms.__getattr__("__version__") == "unknown"
+
+    monkeypatch.undo()
+    vars(swarms).pop("__version__", None)
+
+
+if __name__ == "__main__":
+    pytest.main([__file__])