fix: strict PEP 440 version parsing, update docs and schema description

Address review feedback: remove InvalidVersion fallback that created
mixed str/Version types causing TypeError in comparisons. Instead,
non-PEP 440 versions (e.g. 1.0.0-0.3.7) are rejected explicitly.

- Revert fallback in PackageVersion.__init__ to strict Version() parsing
- Add test verifying non-PEP 440 forms are rejected
- Update schema description from semver reference to PEP 440
- Update docs/config.md and test docs to reference PEP 440
- Update API docs from semver.VersionInfo to packaging.version.Version

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: DavidMinarsch

aea/configurations/data_types.py

@@ -39,7 +39,7 @@
 )
 
 from packaging.specifiers import SpecifierSet
-from packaging.version import InvalidVersion, Version
+from packaging.version import Version
 
 from aea.configurations.constants import (
     AGENT,
@@ -122,13 +122,7 @@ def __init__(self, version_like: PackageVersionLike) -> None:
         if isinstance(version_like, str) and version_like in ("any", "latest"):
             self._version = version_like
         elif isinstance(version_like, str):
-            try:
-                self._version = Version(version_like)
-            except InvalidVersion:
-                # Semver prerelease forms (e.g. 1.0.0-0.3.7) are not PEP 440
-                # but are allowed by the schema regex. Store as raw string so
-                # config loading does not crash.
-                self._version = version_like
+            self._version = Version(version_like)
         elif isinstance(version_like, Version):
             self._version = version_like
         else:

aea/configurations/schemas/definitions.json

@@ -74,7 +74,7 @@
     },
     "semantic_version": {
       "type": "string",
-      "description": "A semantic version number. See https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string",
+      "description": "A version string. Supports PEP 440 versions (MAJOR.MINOR.PATCH with optional pre-release suffixes like rc1, a1, b1).",
       "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
     },
     "pep440_version": {

docs/config.md

@@ -14,7 +14,7 @@ The `aea-config.yaml` defines the AEA project. The compulsory components are lis
 ``` yaml
 agent_name: my_agent                            # Name of the AEA project (must satisfy PACKAGE_REGEX)
 author: fetchai                                 # Author handle of the project's author (must satisfy AUTHOR_REGEX)
-version: 0.1.0                                  # Version of the AEA project (a semantic version number, see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string")
+version: 0.1.0                                  # Version of the AEA project (a version in MAJOR.MINOR.PATCH format, see PEP 440)
 description: A demo project                     # Description of the AEA project
 license: Apache-2.0                             # License of the AEA project
 aea_version: '>=2.0.0, <3.0.0'               # AEA framework version(s) compatible with the AEA project (a version number that matches PEP 440 version schemes, or a comma-separated list of PEP 440 version specifiers, see https://www.python.org/dev/peps/pep-0440/#version-specifiers)
@@ -91,7 +91,7 @@ The `connection.yaml`, which is present in each connection package, has the foll
 ``` yaml
 name: scaffold                                  # Name of the package (must satisfy PACKAGE_REGEX)
 author: fetchai                                 # Author handle of the package's author (must satisfy AUTHOR_REGEX)
-version: 0.1.0                                  # Version of the package (a semantic version number, see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string")
+version: 0.1.0                                  # Version of the package (a version in MAJOR.MINOR.PATCH format, see PEP 440)
 type: connection                                # The type of the package; for connections, it must be "connection"
 description: A scaffold connection              # Description of the package
 license: Apache-2.0                             # License of the package
@@ -117,7 +117,7 @@ The `contract.yaml`, which is present in each contract package, has the followin
 ``` yaml
 name: scaffold                                  # Name of the package (must satisfy PACKAGE_REGEX)
 author: fetchai                                 # Author handle of the package's author (must satisfy AUTHOR_REGEX)
-version: 0.1.0                                  # Version of the package (a semantic version number, see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string")
+version: 0.1.0                                  # Version of the package (a version in MAJOR.MINOR.PATCH format, see PEP 440)
 type: contract                                  # The type of the package; for contracts, it must be "contract"
 description: A scaffold contract                # Description of the package
 license: Apache-2.0                             # License of the package
@@ -139,7 +139,7 @@ The `protocol.yaml`, which is present in each protocol package, has the followin
 ``` yaml
 name: scaffold                                  # Name of the package (must satisfy PACKAGE_REGEX)
 author: fetchai                                 # Author handle of the package's author (must satisfy AUTHOR_REGEX)
-version: 0.1.0                                  # Version of the package (a semantic version number, see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string")
+version: 0.1.0                                  # Version of the package (a version in MAJOR.MINOR.PATCH format, see PEP 440)
 type: protocol                                  # The type of the package; for protocols, it must be "protocol" 
 description: A scaffold protocol                # Description of the package
 license: Apache-2.0                             # License of the package
@@ -158,7 +158,7 @@ The `skill.yaml`, which is present in each protocol package, has the following r
 ``` yaml
 name: scaffold                                  # Name of the package (must satisfy PACKAGE_REGEX)
 author: fetchai                                 # Author handle of the package's author (must satisfy AUTHOR_REGEX)
-version: 0.1.0                                  # Version of the package (a semantic version number, see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string")
+version: 0.1.0                                  # Version of the package (a version in MAJOR.MINOR.PATCH format, see PEP 440)
 type: skill                                     # The type of the package; for skills, it must be "skill"
 description: A scaffold skill                   # Description of the package
 license: Apache-2.0                             # License of the package

tests/test_configurations/test_base.py

@@ -1040,13 +1040,14 @@ def test_package_version_str_format():
         assert str(pv) == version_str
 
 
-def test_package_version_semver_prerelease_fallback():
-    """Test that semver prerelease forms that aren't PEP 440 don't crash."""
+def test_package_version_rejects_non_pep440():
+    """Test that non-PEP 440 semver prerelease forms are rejected explicitly."""
+    from packaging.version import InvalidVersion
+
     exotic = ["1.0.0-0.3.7", "1.0.0-x.7.z.92"]
     for version_str in exotic:
-        pv = PackageVersion(version_str)
-        assert str(pv) == version_str
-        assert pv == PackageVersion(version_str)
+        with pytest.raises(InvalidVersion):
+            PackageVersion(version_str)
 
 
 def test_public_id_with_version_object():

tests/test_docs/test_bash_yaml/md_files/bash-config.md

@@ -7,7 +7,7 @@ LEDGER_ID_REGEX: "^[^\\d\\W]\\w*\\Z"
 ``` yaml
 agent_name: my_agent                            # Name of the AEA project (must satisfy PACKAGE_REGEX)
 author: fetchai                                 # Author handle of the project's author (must satisfy AUTHOR_REGEX)
-version: 0.1.0                                  # Version of the AEA project (a semantic version number, see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string")
+version: 0.1.0                                  # Version of the AEA project (a version in MAJOR.MINOR.PATCH format, see PEP 440)
 description: A demo project                     # Description of the AEA project
 license: Apache-2.0                             # License of the AEA project
 aea_version: '>=2.0.0, <3.0.0'               # AEA framework version(s) compatible with the AEA project (a version number that matches PEP 440 version schemes, or a comma-separated list of PEP 440 version specifiers, see https://www.python.org/dev/peps/pep-0440/#version-specifiers)
@@ -71,7 +71,7 @@ models:                                         # override configurations for mo
 ``` yaml
 name: scaffold                                  # Name of the package (must satisfy PACKAGE_REGEX)
 author: fetchai                                 # Author handle of the package's author (must satisfy AUTHOR_REGEX)
-version: 0.1.0                                  # Version of the package (a semantic version number, see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string")
+version: 0.1.0                                  # Version of the package (a version in MAJOR.MINOR.PATCH format, see PEP 440)
 type: connection                                # The type of the package; for connections, it must be "connection"
 description: A scaffold connection              # Description of the package
 license: Apache-2.0                             # License of the package
@@ -93,7 +93,7 @@ is_abstract: false                              # An optional boolean that if `t
 ``` yaml
 name: scaffold                                  # Name of the package (must satisfy PACKAGE_REGEX)
 author: fetchai                                 # Author handle of the package's author (must satisfy AUTHOR_REGEX)
-version: 0.1.0                                  # Version of the package (a semantic version number, see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string")
+version: 0.1.0                                  # Version of the package (a version in MAJOR.MINOR.PATCH format, see PEP 440)
 type: contract                                  # The type of the package; for contracts, it must be "contract"
 description: A scaffold contract                # Description of the package
 license: Apache-2.0                             # License of the package
@@ -111,7 +111,7 @@ dependencies: {}                                # The python dependencies the pa
 ``` yaml
 name: scaffold                                  # Name of the package (must satisfy PACKAGE_REGEX)
 author: fetchai                                 # Author handle of the package's author (must satisfy AUTHOR_REGEX)
-version: 0.1.0                                  # Version of the package (a semantic version number, see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string")
+version: 0.1.0                                  # Version of the package (a version in MAJOR.MINOR.PATCH format, see PEP 440)
 type: protocol                                  # The type of the package; for protocols, it must be "protocol" 
 description: A scaffold protocol                # Description of the package
 license: Apache-2.0                             # License of the package
@@ -126,7 +126,7 @@ dependencies: {}                                # The python dependencies the pa
 ``` yaml
 name: scaffold                                  # Name of the package (must satisfy PACKAGE_REGEX)
 author: fetchai                                 # Author handle of the package's author (must satisfy AUTHOR_REGEX)
-version: 0.1.0                                  # Version of the package (a semantic version number, see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string")
+version: 0.1.0                                  # Version of the package (a version in MAJOR.MINOR.PATCH format, see PEP 440)
 type: skill                                     # The type of the package; for skills, it must be "skill"
 description: A scaffold skill                   # Description of the package
 license: Apache-2.0                             # License of the package