fix(py#project): use PEP 503 distribution names so nx infers workspace edges (#846)

py#project assigns one name to both the nx project id and the Python
distribution name (`${scope}.${normalizedName}`, e.g. `sojourner.agent`). The
dot makes the distribution name break @nxlv/python's nx-graph dependency
inference: it splits a dotted dependency on `.` (truncating it before lookup),
and looks up uv.lock by the dotted pyproject name while uv writes the lockfile
keyed by the PEP 503 hyphenated name. The result is that a Python workspace
dependency (e.g. an agent on its agent_connection library) never becomes an
edge in the nx project graph, so a change confined to that library does not
invalidate the dependent's cache and a stale build/image can be produced.

Emit a PEP 503 normalised distribution name (lower-cased, runs of `.`/`_`/`-`
collapsed to a single `-`) while keeping the nx project id dotted. The
@nxlv/python uv-project generator accepts a separate `packageName` distinct
from `name`, so the two decouple cleanly: `name` stays the dotted nx id,
`packageName` becomes the hyphenated distribution name written into pyproject
`[project].name` and the root `[tool.uv.sources]` key.

Make addWorkspaceDependencyToPyProject the single, hard-to-misuse entry point
for wiring a Python workspace dependency: it takes the dependent and dependency
projects (not a name string) and derives the dependency's distribution name
from that project's own pyproject.toml, so callers cannot pass the dotted nx id
by mistake. All agent connection generators route through it.

- add normalizeDistributionName to utils/names (+ unit tests)
- py#project: derive distributionName, pass it as uvProjectGenerator packageName
- addWorkspaceDependencyToPyProject takes (dependent, dependency) projects
- agent-connection util: expose getPythonAgentConnectionProject
- update agent connection generators, snapshot + assertions

Co-authored-by: nx-plugin-for-aws <nx-plugin-for-aws@users.noreply.github.com>

Author: nx-plugin-for-aws

packages/nx-plugin/src/py/agent/__snapshots__/generator.spec.ts.snap

@@ -745,7 +745,7 @@ exports[`py#agent generator > should match snapshot for generated files > update
 name = "proj.test_project"
 version = "0.1.0"
 dependencies = [
-  "proj.agent_connection",
+  "proj-agent-connection",
   "aws-lambda-powertools==3.29.0",
   "aws-opentelemetry-distro==0.17.1",
   "bedrock-agentcore==1.13.0",
@@ -763,7 +763,7 @@ dev = [ "fastapi[standard]==0.136.3" ]
 [tool.uv]
 dev-dependencies = [ ]
 
-[tool.uv.sources."proj.agent_connection"]
+[tool.uv.sources.proj-agent-connection]
 workspace = true
 "
 `;

packages/nx-plugin/src/py/agent/a2a-connection/generator.ts

@@ -30,7 +30,7 @@ import {
   addPythonCoreClient,
   getPythonAgentConnectionProjectDir,
   getPythonAgentConnectionModuleName,
-  getPythonAgentConnectionPackageName,
+  getPythonAgentConnectionProject,
   addPythonReExport,
 } from '../../../utils/agent-connection/agent-connection';
 import {
@@ -92,7 +92,6 @@ export const pyAgentA2aConnectionGenerator = async (
 
   const agentConnectionProjectDir = getPythonAgentConnectionProjectDir(tree);
   const agentConnectionModuleName = getPythonAgentConnectionModuleName(tree);
-  const agentConnectionPackageName = getPythonAgentConnectionPackageName(tree);
 
   // Python deps required by the A2A core client + shared auth helper.
   addDependenciesToPyProjectToml(tree, agentConnectionProjectDir, [
@@ -171,8 +170,8 @@ export const pyAgentA2aConnectionGenerator = async (
   // 4. Add workspace dependency from agent project to agent-connection project
   addWorkspaceDependencyToPyProject(
     tree,
-    sourceProject.root,
-    agentConnectionPackageName,
+    sourceProject,
+    getPythonAgentConnectionProject(tree),
   );
 
   // 5. Set up serve-local target dependencies — chain onto the target agent

packages/nx-plugin/src/py/agent/generator.ts

@@ -34,7 +34,7 @@ import { addAgentInfra } from '../../utils/agent-core-constructs/agent-core-cons
 import {
   ensurePythonAgentConnectionProject,
   getPythonAgentConnectionModuleName,
-  getPythonAgentConnectionPackageName,
+  getPythonAgentConnectionProject,
 } from '../../utils/agent-connection/agent-connection';
 import { addWorkspaceDependencyToPyProject } from '../../utils/py';
 
@@ -106,11 +106,10 @@ export const pyAgentGenerator = async (
   // generator wires into this agent.
   await ensurePythonAgentConnectionProject(tree);
   const agentConnectionModuleName = getPythonAgentConnectionModuleName(tree);
-  const agentConnectionPackageName = getPythonAgentConnectionPackageName(tree);
   addWorkspaceDependencyToPyProject(
     tree,
-    project.root,
-    agentConnectionPackageName,
+    project,
+    getPythonAgentConnectionProject(tree),
   );
 
   const templateContext = {

packages/nx-plugin/src/py/agent/mcp-connection/generator.spec.ts

@@ -248,8 +248,9 @@ dependencies = ["strands-agents"]
       'utf-8',
     )!;
 
-    // Check workspace dependency was added
-    expect(pyprojectContent).toContain('proj.agent_connection');
+    // Check workspace dependency was added, keyed by the PEP 503 distribution
+    // name (hyphenated, not the dotted Nx id) so @nxlv/python infers the edge.
+    expect(pyprojectContent).toContain('proj-agent-connection');
   });
 
   it('should update serve-local target with MCP dependency', async () => {

packages/nx-plugin/src/py/agent/mcp-connection/generator.ts

@@ -30,7 +30,7 @@ import {
   addPythonCoreClient,
   getPythonAgentConnectionProjectDir,
   getPythonAgentConnectionModuleName,
-  getPythonAgentConnectionPackageName,
+  getPythonAgentConnectionProject,
   addPythonReExport,
 } from '../../../utils/agent-connection/agent-connection';
 import {
@@ -86,7 +86,6 @@ export const pyAgentMcpConnectionGenerator = async (
 
   const agentConnectionProjectDir = getPythonAgentConnectionProjectDir(tree);
   const agentConnectionModuleName = getPythonAgentConnectionModuleName(tree);
-  const agentConnectionPackageName = getPythonAgentConnectionPackageName(tree);
 
   // Python deps required by the MCP core client + shared auth helper.
   addDependenciesToPyProjectToml(tree, agentConnectionProjectDir, [
@@ -163,8 +162,8 @@ export const pyAgentMcpConnectionGenerator = async (
   // 4. Add workspace dependency from agent project to agent-connection project
   addWorkspaceDependencyToPyProject(
     tree,
-    sourceProject.root,
-    agentConnectionPackageName,
+    sourceProject,
+    getPythonAgentConnectionProject(tree),
   );
 
   // 5. Set up serve-local target dependencies

packages/nx-plugin/src/py/project/generator.ts

@@ -23,7 +23,7 @@ import {
 } from '../../utils/nxlv-python';
 import { withVersions } from '../../utils/versions';
 import { getNpmScope } from '../../utils/npm-scope';
-import { toSnakeCase } from '../../utils/names';
+import { normalizeDistributionName, toSnakeCase } from '../../utils/names';
 import { sortObjectKeys } from '../../utils/object';
 import { updateGitIgnore } from '../../utils/git';
 import {
@@ -41,9 +41,22 @@ export const PY_PROJECT_GENERATOR_INFO: NxGeneratorInfo =
 
 export interface PyProjectDetails {
   /**
-   * Full package name including scope (eg foo.bar)
+   * Fully qualified Nx project id including scope, in dot notation (eg foo.bar).
+   * This is the identifier Nx uses (readProjectConfiguration, the project
+   * graph, target references) and is intentionally kept dotted.
    */
   readonly fullyQualifiedName: string;
+  /**
+   * PEP 503 normalised Python distribution name (eg foo-bar). This is the name
+   * written to the project's `[project].name`, the root `[tool.uv.sources]`
+   * key, and any inter-project dependency string. It is hyphenated (not dotted)
+   * so `uv` and `@nxlv/python` can match it: uv writes `uv.lock` keyed by the
+   * PEP 503 hyphenated name, and `@nxlv/python`'s dependency inference splits a
+   * dotted name on `.` and so would otherwise drop the edge entirely. Keeping
+   * the distribution name decoupled from `fullyQualifiedName` is what lets the
+   * workspace dependency edge appear in the Nx project graph.
+   */
+  readonly distributionName: string;
   /**
    * Directory of the library relative to the root
    */
@@ -72,12 +85,15 @@ export const getPyProjectDetails = (
     schema.moduleName ?? `${scope}_${normalizedName}`,
   );
   const fullyQualifiedName = `${scope}.${normalizedName}`;
+  // The Python distribution name is the PEP 503 normalised form of the
+  // fully qualified name: hyphenated, never dotted. See PyProjectDetails.
+  const distributionName = normalizeDistributionName(fullyQualifiedName);
   // NB: interactive nx generator cli can pass empty string
   const dir = joinPathFragments(
     schema.directory || '.',
     schema.subDirectory || normalizedName,
   );
-  return { dir, fullyQualifiedName, normalizedModuleName };
+  return { dir, fullyQualifiedName, distributionName, normalizedModuleName };
 };
 
 /**
@@ -87,10 +103,8 @@ export const pyProjectGenerator = async (
   tree: Tree,
   schema: PyProjectGeneratorSchema,
 ): Promise<GeneratorCallback> => {
-  const { dir, normalizedModuleName, fullyQualifiedName } = getPyProjectDetails(
-    tree,
-    schema,
-  );
+  const { dir, normalizedModuleName, fullyQualifiedName, distributionName } =
+    getPyProjectDetails(tree, schema);
 
   const pythonPlugin = withVersions(['@nxlv/python']);
   addDependenciesToPackageJson(tree, {}, pythonPlugin);
@@ -132,7 +146,14 @@ export const pyProjectGenerator = async (
   }
 
   await uvProjectGenerator(tree, {
+    // The Nx project id (and `uv.workspace.members` etc.) keys off `name`, so
+    // keep it dotted. `packageName` is the separate PEP 503 distribution name
+    // written to `[project].name` and the root `[tool.uv.sources]` key; it is
+    // hyphenated so `@nxlv/python` infers the workspace dependency edge (it
+    // splits a dotted name on `.` and would otherwise drop it). This split is
+    // the whole fix (see PyProjectDetails.distributionName).
     name: fullyQualifiedName,
+    packageName: distributionName,
     publishable: false,
     buildLockedVersions: true,
     buildBundleLocalDependencies: true,

packages/nx-plugin/src/utils/agent-connection/agent-connection.ts

@@ -53,14 +53,20 @@ export function getPythonAgentConnectionModuleName(tree: Tree): string {
 }
 
 /**
- * Get the fully qualified Python package name of the shared agent-connection project.
+ * Get the shared agent-connection project as `{ name, root }`, suitable for
+ * passing to {@link addWorkspaceDependencyToPyProject} (which derives the
+ * dependency's PEP 503 distribution name from the project itself, so callers
+ * never construct the name).
  */
-export function getPythonAgentConnectionPackageName(tree: Tree): string {
-  const { fullyQualifiedName } = getPyProjectDetails(tree, {
+export function getPythonAgentConnectionProject(tree: Tree): {
+  name: string;
+  root: string;
+} {
+  const { fullyQualifiedName, dir } = getPyProjectDetails(tree, {
     name: PY_AGENT_CONNECTION_NAME,
     directory: joinPathFragments(PACKAGES_DIR, COMMON_DIR),
   });
-  return fullyQualifiedName;
+  return { name: fullyQualifiedName, root: dir };
 }
 
 /**

packages/nx-plugin/src/utils/names.spec.ts

@@ -9,6 +9,7 @@ import {
   toSnakeCase,
   toDotNotation,
   kebabCase,
+  normalizeDistributionName,
   snakeCase,
 } from './names';
 
@@ -593,6 +594,45 @@ describe('names utils', () => {
     });
   });
 
+  describe('normalizeDistributionName', () => {
+    it('should hyphenate dotted scope-qualified names', () => {
+      // The crux: a dotted nx id with an underscored project segment becomes a
+      // fully hyphenated PEP 503 distribution name.
+      expect(normalizeDistributionName('sojourner.agent_connection')).toBe(
+        'sojourner-agent-connection',
+      );
+      expect(normalizeDistributionName('sojourner.agent')).toBe(
+        'sojourner-agent',
+      );
+      expect(normalizeDistributionName('proj.test_project')).toBe(
+        'proj-test-project',
+      );
+    });
+
+    it('should lower-case the name', () => {
+      expect(normalizeDistributionName('MyScope.MyLib')).toBe('myscope-mylib');
+      expect(normalizeDistributionName('Foo_Bar')).toBe('foo-bar');
+    });
+
+    it('should collapse runs of ., _ and - to a single hyphen', () => {
+      expect(normalizeDistributionName('a..b__c--d')).toBe('a-b-c-d');
+      expect(normalizeDistributionName('a._-b')).toBe('a-b');
+    });
+
+    it('should leave an already-normalised name unchanged (idempotent)', () => {
+      expect(normalizeDistributionName('sojourner-agent-connection')).toBe(
+        'sojourner-agent-connection',
+      );
+      const once = normalizeDistributionName('Some.Mixed_Name');
+      expect(normalizeDistributionName(once)).toBe(once);
+    });
+
+    it('should not split camelCase humps (this is not kebab-case)', () => {
+      // PEP 503 only touches ., _ and -; camelCase boundaries are preserved.
+      expect(normalizeDistributionName('myScope.myLib')).toBe('myscope-mylib');
+    });
+  });
+
   describe('cross-function consistency', () => {
     describe('snakeCase and kebabCase should produce consistent word boundaries', () => {
       const testCases = [

packages/nx-plugin/src/utils/names.ts

@@ -59,6 +59,24 @@ export const kebabCase = (str: string): string => {
   );
 };
 
+/**
+ * Normalise a string to a PEP 503 distribution name.
+ *
+ * PEP 503 (https://peps.python.org/pep-0503/#normalized-names) defines the
+ * canonical form of a Python project distribution name: lower-cased, with any
+ * run of `.`, `_` or `-` collapsed to a single `-`. This is the name uv writes
+ * into `uv.lock` and the form `@nxlv/python` expects when inferring workspace
+ * dependency edges from `[project].dependencies` / `[tool.uv.sources]`.
+ *
+ * Importantly this is NOT kebab-case: it does not split on camelCase humps,
+ * spaces or other punctuation, so a dotted nx id like `scope.my_lib` becomes
+ * `scope-my-lib` (and only those three separators are touched).
+ *
+ * eg. `sojourner.agent_connection` -> `sojourner-agent-connection`
+ */
+export const normalizeDistributionName = (str: string): string =>
+  str.toLowerCase().replace(/[._-]+/g, '-');
+
 // Convert a string to a dot notation string (eg. lambda_handler/my_handler.py -> lambda_handler.my_handler)
 export const toDotNotation = (str: string): string =>
   str