RHOAIENG-98954: type the Codeflare facade's keyword arguments (#1179)

* RHOAIENG-98954: type the Codeflare facade's keyword arguments

The facade's primary entrypoints hid their arguments behind **kwargs, so a
misspelled cluster field or a job with no execution target was only ever a
runtime failure. cf.jobs.submit(name=..., entrypoint=...) shipping broken in

- cf.clusters.create() takes **kwargs: Unpack[ClusterConfigKwargs], a TypedDict
  mirroring every ClusterConfiguration field except name and namespace, which
  the handler owns.
- cf.clusters.get() drops **kwargs for explicit verify_tls / write_to_file, the
  only arguments get_cluster accepts.
- cf.jobs.create() and submit() are overloaded on the execution target, making
  "exactly one of cluster_name / cluster_config" a type error rather than only a
  ValueError. Both now delegate to JobHandler._build(), since an overloaded
  method cannot satisfy its own overloads without re-narrowing the target.
- ClusterConfigKwargs and JobOptions are exported, and public-surface.json gains
  the codeflare group it was missing for Codeflare and SDKConfig.

Runtime behaviour is unchanged: the overloads are type-only and the job handler
signatures are identical to before.

The TypedDicts restate names that live elsewhere, so TestFacadeTypeSignatures
guards them — a new ClusterConfiguration field, a changed type, a new job
keyword or a dropped overload each fail a test rather than silently going
unreachable through the facade.

Signed-off-by: Saad Zaher <szaher@redhat.com>

* RHOAIENG-98954: type the Codeflare facade's arguments

The facade hid its arguments behind **kwargs, so a misspelled cluster field or
a job with no execution target was only ever a runtime failure.
cf.jobs.submit(name=..., entrypoint=...) shipping broken in #1091 is the case
in point.

- cf.clusters.create() takes a ClusterConfiguration, the same object
  cf.jobs.create(cluster_config=...) and Cluster() already take. One way to
  describe a cluster across the SDK, and the dataclass does the type checking
  without the facade mirroring 34 fields.
- cf.clusters.get() drops **kwargs for explicit verify_tls / write_to_file, the
  only arguments get_cluster accepts.
- cf.jobs.create() and submit() are overloaded on the execution target, making
  "exactly one of cluster_name / cluster_config" a type error rather than only
  a ValueError. Both delegate to JobHandler._build(), since an overloaded
  method cannot satisfy its own overloads without re-narrowing the target.
- JobOptions is exported, and public-surface.json gains the codeflare group it
  was missing for Codeflare and SDKConfig.

The handler resolves the namespace and injects it with copy.copy rather than
dataclasses.replace: ClusterConfiguration.__post_init__ is not idempotent — it
merges the default accelerator mapping into extended_resource_mapping and then
rejects the merged result — so reconstructing a configured instance raises.
Covered by test_create_accepts_a_fully_configured_config.

The facade is unreleased (#1091 is in no tag), so this changes no published API.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Signed-off-by: Saad Zaher <szaher@redhat.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: szaher

AGENTS.md

@@ -10,13 +10,16 @@ objects bound to that client. The lower-level `Cluster` / `RayJob` classes
 remain public and usable directly.
 
 ```python
-from codeflare_sdk import Codeflare, SDKConfig
+from codeflare_sdk import ClusterConfiguration, Codeflare, SDKConfig
 
 cf = Codeflare(config=SDKConfig(namespace="my-project"))
-cluster = cf.clusters.create(name="my-cluster", num_workers=2)
+cluster = cf.clusters.create(ClusterConfiguration(name="my-cluster", num_workers=2))
 cluster.apply()
 ```
 
+`ClusterConfiguration` is the one way to describe a cluster: `cf.clusters.create()`,
+`cf.jobs.create(cluster_config=...)` and `Cluster()` all take it.
+
 ## Repository Structure
 
 | Directory | Description |
@@ -166,6 +169,9 @@ still lists `Authentication`, `KubeConfiguration`, `TokenAuthentication` and
 `KubeConfigFileAuthentication`, which were removed and now raise `ImportError`
 (tracked in RHOAIENG-98754, pending a decision on restoring compatibility shims).
 
+The `codeflare` entry covers the single entrypoint: `Codeflare`, `SDKConfig`,
+and the `JobOptions` TypedDict shared by the `cf.jobs` overloads.
+
 Design-level architecture: `docs/designs/CodeFlare-SDK-design-doc.md`.
 User-facing Sphinx docs: `docs/sphinx/`.
 
@@ -271,6 +277,14 @@ Real examples for the most common change types. Follow these patterns, not descr
     (`build_ray_cluster_spec`, line 96)
 
   A field added to only one builder is silently dropped by the other path.
+- Nothing to add on the facade side: `cf.clusters.create()` takes a
+  `ClusterConfiguration` rather than `**kwargs`, so a new field reaches it for
+  free (RHOAIENG-98954).
+- `__post_init__` is **not idempotent** — it merges the default accelerator
+  mapping into `extended_resource_mapping` and then rejects the merged result.
+  `dataclasses.replace()` on a configured instance therefore raises. Use
+  `copy.copy()` and set the attribute, as `ClusterHandler.create` does when it
+  injects the namespace.
 - Tests: `src/codeflare_sdk/ray/cluster/test_config.py` — see `test_config_creation_all_parameters`
   and `test_autoscaling_config_valid` for the pattern.
 
@@ -281,6 +295,13 @@ Real examples for the most common change types. Follow these patterns, not descr
   fixture from `src/codeflare_sdk/ray/rayjobs/test/conftest.py`.
 - Methods reaching the Kubernetes API need `@_bound_to_api_client` — see
   "Client isolation" above.
+- `cf.jobs.create()` / `cf.jobs.submit()` are `@overload`ed so that passing
+  neither or both of `cluster_name` / `cluster_config` is a type error, not just
+  a runtime `ValueError`. A new keyword argument goes in three places: the
+  implementation signature, the `JobOptions` TypedDict, and the docstring. Both
+  methods delegate to `JobHandler._build()`; they cannot call each other,
+  because an overloaded method cannot satisfy its own overloads without
+  re-narrowing the target.
 
 ### Adding unit and e2e tests
 

README.md

@@ -40,7 +40,7 @@ Kubernetes client, so clusters and jobs created from it keep using that client.
 
 ```python
 from kube_authkit import AuthConfig
-from codeflare_sdk import Codeflare, SDKConfig
+from codeflare_sdk import ClusterConfiguration, Codeflare, SDKConfig
 
 # Option 1: Auto-detect authentication (kubeconfig or in-cluster service account)
 cf = Codeflare(config=SDKConfig(namespace='my-project'))
@@ -66,8 +66,9 @@ cf = Codeflare(config=SDKConfig(
     namespace='my-project',
 ))
 
-# Now create your cluster
-cluster = cf.clusters.create(name='my-cluster', num_workers=2)
+# Now create your cluster. Every SDK entrypoint that takes a cluster
+# description takes the same ClusterConfiguration object.
+cluster = cf.clusters.create(ClusterConfiguration(name='my-cluster', num_workers=2))
 cluster.apply()
 ```
 

demo-notebooks/guided-demos/6_single_entrypoint.ipynb

@@ -44,7 +44,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from codeflare_sdk import Codeflare, SDKConfig\n",
+    "from codeflare_sdk import ClusterConfiguration, Codeflare, SDKConfig\n",
     "from kube_authkit import AuthConfig"
    ]
   },
@@ -116,9 +116,10 @@
    "source": [
     "## Step 3: Create and bring up a Ray cluster\n",
     "\n",
-    "Use `cf.clusters.create()` to build a `Cluster` object. All keyword arguments\n",
-    "are forwarded to `ClusterConfiguration`. The namespace is inherited from\n",
-    "`SDKConfig` unless you override it."
+    "Use `cf.clusters.create()` to build a `Cluster` object from a\n",
+    "`ClusterConfiguration` — the same object `cf.jobs` and `Cluster()` take. The\n",
+    "namespace is inherited from `SDKConfig` unless the config or the call overrides\n",
+    "it."
    ]
   },
   {
@@ -129,20 +130,22 @@
    "outputs": [],
    "source": [
     "cluster = cf.clusters.create(\n",
-    "    name=\"entrypoint-demo\",\n",
-    "    num_workers=2,\n",
-    "    head_cpu_requests=\"500m\",\n",
-    "    head_cpu_limits=\"500m\",\n",
-    "    head_memory_requests=5,\n",
-    "    head_memory_limits=8,\n",
-    "    worker_cpu_requests=\"250m\",\n",
-    "    worker_cpu_limits=1,\n",
-    "    worker_memory_requests=4,\n",
-    "    worker_memory_limits=6,\n",
-    "    head_extended_resource_requests={\"nvidia.com/gpu\": 0},\n",
-    "    worker_extended_resource_requests={\"nvidia.com/gpu\": 0},\n",
-    "    write_to_file=False,\n",
-    "    # local_queue=\"your-local-queue\",  # optional — auto-detected if omitted\n",
+    "    ClusterConfiguration(\n",
+    "        name=\"entrypoint-demo\",\n",
+    "        num_workers=2,\n",
+    "        head_cpu_requests=\"500m\",\n",
+    "        head_cpu_limits=\"500m\",\n",
+    "        head_memory_requests=5,\n",
+    "        head_memory_limits=8,\n",
+    "        worker_cpu_requests=\"250m\",\n",
+    "        worker_cpu_limits=1,\n",
+    "        worker_memory_requests=4,\n",
+    "        worker_memory_limits=6,\n",
+    "        head_extended_resource_requests={\"nvidia.com/gpu\": 0},\n",
+    "        worker_extended_resource_requests={\"nvidia.com/gpu\": 0},\n",
+    "        write_to_file=False,\n",
+    "        # local_queue=\"your-local-queue\",  # optional — auto-detected if omitted\n",
+    "    )\n",
     ")"
    ]
   },
@@ -193,7 +196,21 @@
    "id": "m1b2c3d4",
    "metadata": {},
    "outputs": [],
-   "source": "from codeflare_sdk import ClusterConfiguration\n\njob = cf.jobs.submit(\n    name=\"entrypoint-demo-job\",\n    entrypoint=\"python -c 'import ray; ray.init(); print(\\\"Hello from the Codeflare entrypoint!\\\")'\",\n    cluster_config=ClusterConfiguration(\n        head_memory_requests=6,\n        head_memory_limits=8,\n        num_workers=1,\n        worker_cpu_requests=1,\n        worker_cpu_limits=1,\n        worker_memory_requests=4,\n        worker_memory_limits=6,\n    ),\n)"
+   "source": [
+    "job = cf.jobs.submit(\n",
+    "    name=\"entrypoint-demo-job\",\n",
+    "    entrypoint=\"python -c 'import ray; ray.init(); print(\\\"Hello from the Codeflare entrypoint!\\\")'\",\n",
+    "    cluster_config=ClusterConfiguration(\n",
+    "        head_memory_requests=6,\n",
+    "        head_memory_limits=8,\n",
+    "        num_workers=1,\n",
+    "        worker_cpu_requests=1,\n",
+    "        worker_cpu_limits=1,\n",
+    "        worker_memory_requests=4,\n",
+    "        worker_memory_limits=6,\n",
+    "    ),\n",
+    ")"
+   ]
   },
   {
    "cell_type": "code",

docs/api/public-surface.json

@@ -18,6 +18,15 @@
         "list_all_clusters"
       ]
     },
+    "codeflare": {
+      "module": "codeflare_sdk.codeflare",
+      "symbols": [
+        "Codeflare",
+        "SDKConfig",
+        "JobOptions"
+      ],
+      "notes": "Single entrypoint. JobOptions is a TypedDict describing the shared keyword arguments of the cf.jobs.create()/submit() overloads; it carries no runtime behaviour."
+    },
     "rayjobs": {
       "module": "codeflare_sdk.ray.rayjobs",
       "symbols": [

src/codeflare_sdk/__init__.py

@@ -14,7 +14,7 @@
 
 from .common.widgets import view_clusters
 
-from .codeflare import Codeflare, SDKConfig
+from .codeflare import Codeflare, SDKConfig, JobOptions
 
 from .common.kueue import (
     list_local_queues,