PyPI

AXM reads Python extension metadata from an agent-extensions.json package-data file named by the [agentExtensions] entry-point group. This is the two-way linking model applied to the PyPI ecosystem.

Add agent-extensions.json to an importable package and name it from the agentExtensions entry-point group:

# pyproject.toml
[project]
name = "agentxm-example-tinyflags"
version = "0.1.0"

[project.entry-points.agentExtensions]
metadata = "agentxm_example_tinyflags:agent-extensions.json"

The sidecar contains the portable contract. Each entry is an extension reference (@owner/<type>/<name>):

// agentxm_example_tinyflags/agent-extensions.json
{
  "$schema": "https://axm.sh/schemas/agent-extensions.schema.json",
  "agentExtensions": [{ "ref": "@examples/packs/python-pypi-tinyflags" }],
}

Include the sidecar as package data so it appears in the wheel and its RECORD.

Keep recommendations identity-only — omit versionRange. AXM resolves the reference to the newest matching extension version and pins it in the user's axm.lock. Prefer recommending a single pack so you keep one stable reference while its contents evolve.

Add a semver versionRange only when your package genuinely pairs with a bounded major line of the extension:

{
  "agentExtensions": [
    {
      "ref": "@examples/packs/python-pypi-tinyflags",
      "versionRange": "^1.0.0",
    },
  ],
}

On the extension manifest (skill.json, pack.json, subagent.json, …), add a packages array with a PyPI purl:

// pack.json
{
  "packages": [{ "purl": "pkg:pypi/agentxm-example-tinyflags" }],
}

Use the package's normalized PyPI name in the purl (lowercase, with runs of ., _, or - collapsed to a single -), matching how PyPI itself indexes the project.

Default to identity-only. Add a VERS versionRange with the pypi scheme only when the extension depends on package APIs introduced or removed in a known range:

{
  "packages": [
    {
      "purl": "pkg:pypi/agentxm-example-tinyflags",
      "versionRange": "vers:pypi/>=0.1.0|<1.0.0",
    },
  ],
}

When the PyPI package recommends an extension through the AgentXM Registry and that extension names the package as a companion via its purl, AXM derives official status for the pair — no extra flag. See Official extensions.

The python-pypi-lib and python-pypi-app directories in polyglot-examples are the working fixtures for everything above. The library publishes a TinyFlags companion pack and recommends it from package data named by the [agentExtensions] entry-point group; the pack and each skill declare the library's PyPI purl as an identity-only companion package.