tangle-cli 0.0.1a1__tar.gz → 0.0.1a3__tar.gz

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: tangle-cli
-Version: 0.0.1a1
+Version: 0.0.1a3
 Summary: CLI for Tangle, the open-source ML pipeline orchestration platform
 Author: Alexey Volkov, Tangle authors
 Author-email: Alexey Volkov <alexey.volkov@ark-kun.com>
@@ -13,8 +13,8 @@ Requires-Dist: platformdirs>=4.10.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.32.0
+Requires-Dist: tangle-api==0.0.1a3
 Requires-Dist: tomli>=2.0 ; python_full_version < '3.11'
-Requires-Dist: tangle-api==0.1.0 ; extra == 'native'
 Requires-Python: >=3.10
 Project-URL: Homepage, https://tangleml.com
 Project-URL: Documentation, https://tangleml.com/docs/
@@ -58,7 +58,7 @@ By default `tangle api` uses `--schema-source auto`, which means official static
 
 `tangle sdk` commands are hand-written workflows. They can be:
 
-- **local-only**: no generated/native API bindings required, e.g. pipeline validation/layout and component generation;
+- **local-only**: no generated API bindings required, e.g. pipeline validation/layout and component generation;
 - **API-backed**: use the generated client but add domain behavior, e.g. pipeline-run submit payload construction, hydration, artifact lookup, publishing/version checks, or config batching.
 
 Current SDK groups include:
@@ -111,22 +111,22 @@ Use `--log-type none` for quiet machine-readable runs, and `--log-type file` to
 The repository contains two Python import packages with different responsibilities:
 
 - `tangle_cli` is hand-written. It contains CLI wiring, SDK/business helpers, local pipeline/component workflows, dynamic API discovery, codegen, shared runtime classes, logging, and extension classes.
-- `tangle_api` is generated/native. It contains checked-in generated Pydantic models, generated endpoint operation methods, and the official OpenAPI snapshot.
+- `tangle_api` is generated/static. It contains checked-in generated Pydantic models, generated endpoint operation methods, and the official OpenAPI snapshot.
 
-The default `tangle-cli` package keeps the top-level import and local-only SDK commands native-free. Install the native extra when you want static API-backed commands and the handwritten `TangleApiClient` wrapper to use the checked-in generated bindings:
+The default public `tangle-cli` package depends on the matching `tangle-api` package, so normal installs include the checked-in generated bindings used by static API-backed commands and the handwritten `TangleApiClient` wrapper:
 
 ```bash
-pip install 'tangle-cli[native]'
+pip install tangle-cli
 ```
 
-In this workspace, `uv` installs the workspace `tangle-api` package for development and tests:
+The `native` extra remains as a compatibility no-op alias for older install instructions. In this workspace, `uv` installs the workspace `tangle-api` package for development and tests:
 
 ```bash
 uv run tangle api --help
 uv run tangle sdk pipelines validate pipeline.yaml
 ```
 
-If you are embedding `tangle_cli` in a downstream project, you can provide your own local `tangle_api.generated` package produced from your backend schema instead of using this repo's official generated package.
+Custom API/codegen users can still run codegen from the fully capable install; generating bindings does not require removing the official `tangle-api` package. For project-local generated APIs, generate into a local source tree such as `src/tangle_api/generated` (and `src/tangle_api/schema/openapi.json` when you want `tangle api --schema-source official`) and run from that project so local `src/tangle_api` shadows site-packages. For packaged custom APIs, publish/provide a distribution named `tangle-api` with a version compatible with this `tangle-cli` release (for example `0.0.1a3+yourorg` for a `tangle-cli` dependency on `tangle-api==0.0.1a3`) via a private index, `--find-links`, or uv sources. As an expert escape hatch, `--no-deps` installs only `tangle-cli` and skips all dependencies, so that environment must manually provide every required runtime dependency plus its generated/custom `tangle_api`; this is acceptable for controlled codegen/custom scenarios but not normal UX.
 
 ## Quick command examples
 
@@ -229,9 +229,9 @@ uv run tangle api reset-cache --base-url https://api.example
 
 Schema source modes are:
 
-- `--schema-source auto` (default): official static operations plus cached-only backend extensions when a cache exists. Requires the native `tangle-api` package for official operations.
-- `--schema-source official`: only the checked-in official static schema. Requires the native `tangle-api` package.
-- `--schema-source cache`: only the schema previously written by `tangle api refresh` for the selected base URL. Does not require the native package.
+- `--schema-source auto` (default): official static operations plus cached-only backend extensions when a cache exists. Normal `tangle-cli` installs include the `tangle-api` package needed for official operations; custom API projects can shadow or replace that package as described in the codegen section.
+- `--schema-source official`: only the checked-in official static schema from `tangle-api` (or a compatible custom `tangle-api` package on your environment's import path).
+- `--schema-source cache`: only the schema previously written by `tangle api refresh` for the selected base URL. This is the custom/source-checkout fallback when a consumer environment does not provide an importable `tangle_api.schema` package.
 
 For resource help, put `--schema-source` on the resource group:
 
@@ -331,7 +331,7 @@ existing = client.find_existing_components(
 
 `TangleApiClient` is handwritten in `tangle_cli.client` and inherits generated endpoint methods from `tangle_api.generated.operations.GeneratedTangleApiOperations`. The generated endpoint methods call the handwritten transport/request logic. Handwritten semantic helpers such as `find_existing_components(...)` return domain models and normalize common compatibility cases.
 
-The top-level `import tangle_cli` is lightweight and does not import native static bindings. Install the native extra or otherwise provide a local `tangle_api.generated` package before importing `tangle_cli.client`.
+The top-level `import tangle_cli` is lightweight and does not import static bindings eagerly. Normal installs include `tangle-api`; source checkouts or downstream embeddings may instead provide a local `tangle_api.generated` package before importing `tangle_cli.client`.
 
 ## Codegen/autogen from OpenAPI
 
@@ -362,6 +362,17 @@ uv run python -m tangle_cli.openapi.codegen \
   --out src/tangle_api/generated
 ```
 
+For a project-local custom API package, write both the schema snapshot and generated modules under that project's source tree, then run tools/tests from the project environment so `src/tangle_api` is earlier on `sys.path` than the official site-packages package:
+
+```bash
+uv run python -m tangle_cli.openapi.codegen \
+  --openapi-url https://api.example/openapi.json \
+  --openapi src/tangle_api/schema/openapi.json \
+  --out src/tangle_api/generated
+```
+
+That project-local `tangle_api` package can be an editable/package source tree. If you ship the custom API bindings as a wheel or source distribution, use the distribution name `tangle-api` and a compatible version for the `tangle-cli` release you are using. A PEP 440 local version such as `0.0.1a3+yourorg` can satisfy a public `==0.0.1a3` dependency while distinguishing your private build. Provide that package through your private index, `--find-links`, or uv source configuration so the resolver chooses it instead of the public official package.
+
 Generate from a backend checkout explicitly:
 
 ```bash
@@ -372,48 +383,29 @@ uv run --group codegen python -m tangle_cli.openapi.codegen \
 
 Important codegen options:
 
-- `--out`: directory that receives `__init__.py`, `models.py`, and `operations.py`. Defaults to `packages/tangle-api/src/tangle_api/generated`.
+- `--out`: directory that receives `__init__.py`, `runtime.py`, `models.py`, and `operations.py`. Defaults to `packages/tangle-api/src/tangle_api/generated`.
 - `--operations-class-name`: generated operations mixin class name. Defaults to `GeneratedTangleApiOperations`.
-- `--model-extension-module`: importable module with `MODEL_EXTENSIONS`; repeat to compose modules.
 - `--model-alias`: expose a stable public model name from one or more source schema names, e.g. `ComponentSpec=ComponentSpecOutput,ComponentSpecInput`.
 - `--request-body-schema` / `--request-body-schema-file`: override a specific operation's JSON request-body schema without mutating the fetched OpenAPI document.
 
 At runtime, more `tangle api ...` commands become available in two ways:
 
-1. Static codegen: regenerate and install/provide a `tangle_api.generated` package for the schema.
+1. Static codegen: regenerate and install/provide a local or packaged `tangle_api` package containing `tangle_api.generated` and, for official-schema CLI discovery, `tangle_api.schema`.
 2. Dynamic cache: run `tangle api refresh --base-url ...` and use `--schema-source auto` or `--schema-source cache` to expose cached-only operations through the dynamic CLI.
 
-## Generated model extension pattern
+The supported workaround hierarchy for custom API consumers is: prefer a project-local `src/tangle_api` package that shadows site-packages for that project; if distributing bindings, prefer a compatible private `tangle-api` distribution; reserve `--no-deps` installs or manual uninstalls of the official package for controlled expert environments where you manually provide all dependencies and the generated/custom `tangle_api` package.
 
-Generated models use a generated implementation base plus a stable public subclass. For example, codegen emits this shape for a model with a handwritten extension:
+## Runtime generated model extension pattern
+
+`tangle_api.generated.models` is a leaf package and codegen emits plain generated Pydantic models directly:
 
 ```python
-class _ComponentSpecGenerated(TangleGeneratedModel):
+class ComponentSpec(TangleGeneratedModel):
     name: Any = None
     # generated OpenAPI fields...
-
-class ComponentSpec(ComponentSpecExtensions, _ComponentSpecGenerated):
-    pass
-```
-
-The public class is a subclass rather than an alias because the public class name is the stable contract while the generated base can be regenerated. Subclassing lets the public class keep the OpenAPI/Pydantic fields from `_ComponentSpecGenerated` and add or override behavior through normal Python MRO.
-
-Extension bases are placed to the **left** of the generated base:
-
-```python
-class ComponentSpec(ComponentSpecExtensions, _ComponentSpecGenerated):
-    pass
-```
-
-That means extension methods/properties override generated-base behavior when names overlap, while generated fields and `TangleGeneratedModel` runtime helpers such as `to_dict()` remain available.
-
-The built-in default extension module is:
-
-```text
-tangle_cli.generated_model_extensions
 ```
 
-It defines:
+Generated models do not import `tangle_cli` and codegen does not bake downstream extension modules into `tangle_api`. Downstream packages compose their own extended model namespace at runtime. In `tangle_cli.models`, the default CLI mixins are declared in `tangle_cli.generated_model_extensions`:
 
 ```python
 MODEL_EXTENSIONS = {
@@ -423,42 +415,11 @@ MODEL_EXTENSIONS = {
 }
 ```
 
-During codegen, `tangle_api.generated.models` imports those extension classes from `tangle_cli.generated_model_extensions`. This preserves the package boundary: `tangle_api` remains generated bindings, while `tangle_cli` owns handwritten runtime and extension behavior.
-
-Downstream projects can layer their own extensions:
-
-```python
-# my_project/tangle_model_extensions.py
-class MyComponentSpecExtensions:
-    @property
-    def owning_team(self) -> str | None:
-        return (self.metadata or {}).get("annotations", {}).get("team")
-
-MODEL_EXTENSIONS = {
-    "ComponentSpec": "MyComponentSpecExtensions",
-}
-```
-
-```bash
-uv run python -m tangle_cli.openapi.codegen \
-  --openapi-url https://api.example/openapi.json \
-  --out src/tangle_api/generated \
-  --model-extension-module my_project.tangle_model_extensions
-```
-
-The default module is applied first. Repeated `--model-extension-module` values are applied in order, and later/downstream modules become leftmost in the generated public class MRO, so they override earlier/default extensions. If two modules export the same extension class name, codegen imports them with deterministic aliases.
-
-Pass an empty string to disable built-in default extensions:
-
-```bash
-uv run python -m tangle_cli.openapi.codegen \
-  --from-snapshot \
-  --model-extension-module ""
-```
+`tangle_cli.models.compose_models(...)` reads those mappings and creates subclasses in the `tangle_cli.models` namespace, e.g. `ComponentSpec(ComponentSpecExtensions, tangle_api.generated.models.ComponentSpec)`, without mutating `tangle_api.generated.models`. The generated operations layer also calls `_response_model(model_name, default)` so `TangleApiClient` can deserialize responses into the CLI-composed classes while the base `GeneratedTangleApiOperations` remains downstream-agnostic.
 
-The same empty-string sentinel can disable built-in `--model-alias` defaults. Built-in aliases keep stable public model names such as `ComponentSpec` even when a backend schema uses names like `ComponentSpecOutput` or `ComponentSpecInput`.
+Downstream projects can use the same pattern in their own namespace: import base classes from `tangle_api.generated.models`, define method/property-only mixins plus a `MODEL_EXTENSIONS` mapping, and compose subclasses locally. Avoid global monkey-patching of `tangle_api.generated.models`.
 
-Extension classes should be importable from their modules and should not import generated model classes. They should be mixins over generated data, not replacements for generated schemas.
+Built-in `--model-alias` defaults still keep stable public model names such as `ComponentSpec` even when a backend schema uses names like `ComponentSpecOutput` or `ComponentSpecInput`.
 
 ## Extending SDK behavior
 

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/README.md

@@ -33,7 +33,7 @@ By default `tangle api` uses `--schema-source auto`, which means official static
 
 `tangle sdk` commands are hand-written workflows. They can be:
 
-- **local-only**: no generated/native API bindings required, e.g. pipeline validation/layout and component generation;
+- **local-only**: no generated API bindings required, e.g. pipeline validation/layout and component generation;
 - **API-backed**: use the generated client but add domain behavior, e.g. pipeline-run submit payload construction, hydration, artifact lookup, publishing/version checks, or config batching.
 
 Current SDK groups include:
@@ -86,22 +86,22 @@ Use `--log-type none` for quiet machine-readable runs, and `--log-type file` to
 The repository contains two Python import packages with different responsibilities:
 
 - `tangle_cli` is hand-written. It contains CLI wiring, SDK/business helpers, local pipeline/component workflows, dynamic API discovery, codegen, shared runtime classes, logging, and extension classes.
-- `tangle_api` is generated/native. It contains checked-in generated Pydantic models, generated endpoint operation methods, and the official OpenAPI snapshot.
+- `tangle_api` is generated/static. It contains checked-in generated Pydantic models, generated endpoint operation methods, and the official OpenAPI snapshot.
 
-The default `tangle-cli` package keeps the top-level import and local-only SDK commands native-free. Install the native extra when you want static API-backed commands and the handwritten `TangleApiClient` wrapper to use the checked-in generated bindings:
+The default public `tangle-cli` package depends on the matching `tangle-api` package, so normal installs include the checked-in generated bindings used by static API-backed commands and the handwritten `TangleApiClient` wrapper:
 
 ```bash
-pip install 'tangle-cli[native]'
+pip install tangle-cli
 ```
 
-In this workspace, `uv` installs the workspace `tangle-api` package for development and tests:
+The `native` extra remains as a compatibility no-op alias for older install instructions. In this workspace, `uv` installs the workspace `tangle-api` package for development and tests:
 
 ```bash
 uv run tangle api --help
 uv run tangle sdk pipelines validate pipeline.yaml
 ```
 
-If you are embedding `tangle_cli` in a downstream project, you can provide your own local `tangle_api.generated` package produced from your backend schema instead of using this repo's official generated package.
+Custom API/codegen users can still run codegen from the fully capable install; generating bindings does not require removing the official `tangle-api` package. For project-local generated APIs, generate into a local source tree such as `src/tangle_api/generated` (and `src/tangle_api/schema/openapi.json` when you want `tangle api --schema-source official`) and run from that project so local `src/tangle_api` shadows site-packages. For packaged custom APIs, publish/provide a distribution named `tangle-api` with a version compatible with this `tangle-cli` release (for example `0.0.1a3+yourorg` for a `tangle-cli` dependency on `tangle-api==0.0.1a3`) via a private index, `--find-links`, or uv sources. As an expert escape hatch, `--no-deps` installs only `tangle-cli` and skips all dependencies, so that environment must manually provide every required runtime dependency plus its generated/custom `tangle_api`; this is acceptable for controlled codegen/custom scenarios but not normal UX.
 
 ## Quick command examples
 
@@ -204,9 +204,9 @@ uv run tangle api reset-cache --base-url https://api.example
 
 Schema source modes are:
 
-- `--schema-source auto` (default): official static operations plus cached-only backend extensions when a cache exists. Requires the native `tangle-api` package for official operations.
-- `--schema-source official`: only the checked-in official static schema. Requires the native `tangle-api` package.
-- `--schema-source cache`: only the schema previously written by `tangle api refresh` for the selected base URL. Does not require the native package.
+- `--schema-source auto` (default): official static operations plus cached-only backend extensions when a cache exists. Normal `tangle-cli` installs include the `tangle-api` package needed for official operations; custom API projects can shadow or replace that package as described in the codegen section.
+- `--schema-source official`: only the checked-in official static schema from `tangle-api` (or a compatible custom `tangle-api` package on your environment's import path).
+- `--schema-source cache`: only the schema previously written by `tangle api refresh` for the selected base URL. This is the custom/source-checkout fallback when a consumer environment does not provide an importable `tangle_api.schema` package.
 
 For resource help, put `--schema-source` on the resource group:
 
@@ -306,7 +306,7 @@ existing = client.find_existing_components(
 
 `TangleApiClient` is handwritten in `tangle_cli.client` and inherits generated endpoint methods from `tangle_api.generated.operations.GeneratedTangleApiOperations`. The generated endpoint methods call the handwritten transport/request logic. Handwritten semantic helpers such as `find_existing_components(...)` return domain models and normalize common compatibility cases.
 
-The top-level `import tangle_cli` is lightweight and does not import native static bindings. Install the native extra or otherwise provide a local `tangle_api.generated` package before importing `tangle_cli.client`.
+The top-level `import tangle_cli` is lightweight and does not import static bindings eagerly. Normal installs include `tangle-api`; source checkouts or downstream embeddings may instead provide a local `tangle_api.generated` package before importing `tangle_cli.client`.
 
 ## Codegen/autogen from OpenAPI
 
@@ -337,6 +337,17 @@ uv run python -m tangle_cli.openapi.codegen \
   --out src/tangle_api/generated
 ```
 
+For a project-local custom API package, write both the schema snapshot and generated modules under that project's source tree, then run tools/tests from the project environment so `src/tangle_api` is earlier on `sys.path` than the official site-packages package:
+
+```bash
+uv run python -m tangle_cli.openapi.codegen \
+  --openapi-url https://api.example/openapi.json \
+  --openapi src/tangle_api/schema/openapi.json \
+  --out src/tangle_api/generated
+```
+
+That project-local `tangle_api` package can be an editable/package source tree. If you ship the custom API bindings as a wheel or source distribution, use the distribution name `tangle-api` and a compatible version for the `tangle-cli` release you are using. A PEP 440 local version such as `0.0.1a3+yourorg` can satisfy a public `==0.0.1a3` dependency while distinguishing your private build. Provide that package through your private index, `--find-links`, or uv source configuration so the resolver chooses it instead of the public official package.
+
 Generate from a backend checkout explicitly:
 
 ```bash
@@ -347,48 +358,29 @@ uv run --group codegen python -m tangle_cli.openapi.codegen \
 
 Important codegen options:
 
-- `--out`: directory that receives `__init__.py`, `models.py`, and `operations.py`. Defaults to `packages/tangle-api/src/tangle_api/generated`.
+- `--out`: directory that receives `__init__.py`, `runtime.py`, `models.py`, and `operations.py`. Defaults to `packages/tangle-api/src/tangle_api/generated`.
 - `--operations-class-name`: generated operations mixin class name. Defaults to `GeneratedTangleApiOperations`.
-- `--model-extension-module`: importable module with `MODEL_EXTENSIONS`; repeat to compose modules.
 - `--model-alias`: expose a stable public model name from one or more source schema names, e.g. `ComponentSpec=ComponentSpecOutput,ComponentSpecInput`.
 - `--request-body-schema` / `--request-body-schema-file`: override a specific operation's JSON request-body schema without mutating the fetched OpenAPI document.
 
 At runtime, more `tangle api ...` commands become available in two ways:
 
-1. Static codegen: regenerate and install/provide a `tangle_api.generated` package for the schema.
+1. Static codegen: regenerate and install/provide a local or packaged `tangle_api` package containing `tangle_api.generated` and, for official-schema CLI discovery, `tangle_api.schema`.
 2. Dynamic cache: run `tangle api refresh --base-url ...` and use `--schema-source auto` or `--schema-source cache` to expose cached-only operations through the dynamic CLI.
 
-## Generated model extension pattern
+The supported workaround hierarchy for custom API consumers is: prefer a project-local `src/tangle_api` package that shadows site-packages for that project; if distributing bindings, prefer a compatible private `tangle-api` distribution; reserve `--no-deps` installs or manual uninstalls of the official package for controlled expert environments where you manually provide all dependencies and the generated/custom `tangle_api` package.
 
-Generated models use a generated implementation base plus a stable public subclass. For example, codegen emits this shape for a model with a handwritten extension:
+## Runtime generated model extension pattern
+
+`tangle_api.generated.models` is a leaf package and codegen emits plain generated Pydantic models directly:
 
 ```python
-class _ComponentSpecGenerated(TangleGeneratedModel):
+class ComponentSpec(TangleGeneratedModel):
     name: Any = None
     # generated OpenAPI fields...
-
-class ComponentSpec(ComponentSpecExtensions, _ComponentSpecGenerated):
-    pass
-```
-
-The public class is a subclass rather than an alias because the public class name is the stable contract while the generated base can be regenerated. Subclassing lets the public class keep the OpenAPI/Pydantic fields from `_ComponentSpecGenerated` and add or override behavior through normal Python MRO.
-
-Extension bases are placed to the **left** of the generated base:
-
-```python
-class ComponentSpec(ComponentSpecExtensions, _ComponentSpecGenerated):
-    pass
-```
-
-That means extension methods/properties override generated-base behavior when names overlap, while generated fields and `TangleGeneratedModel` runtime helpers such as `to_dict()` remain available.
-
-The built-in default extension module is:
-
-```text
-tangle_cli.generated_model_extensions
 ```
 
-It defines:
+Generated models do not import `tangle_cli` and codegen does not bake downstream extension modules into `tangle_api`. Downstream packages compose their own extended model namespace at runtime. In `tangle_cli.models`, the default CLI mixins are declared in `tangle_cli.generated_model_extensions`:
 
 ```python
 MODEL_EXTENSIONS = {
@@ -398,42 +390,11 @@ MODEL_EXTENSIONS = {
 }
 ```
 
-During codegen, `tangle_api.generated.models` imports those extension classes from `tangle_cli.generated_model_extensions`. This preserves the package boundary: `tangle_api` remains generated bindings, while `tangle_cli` owns handwritten runtime and extension behavior.
-
-Downstream projects can layer their own extensions:
-
-```python
-# my_project/tangle_model_extensions.py
-class MyComponentSpecExtensions:
-    @property
-    def owning_team(self) -> str | None:
-        return (self.metadata or {}).get("annotations", {}).get("team")
-
-MODEL_EXTENSIONS = {
-    "ComponentSpec": "MyComponentSpecExtensions",
-}
-```
-
-```bash
-uv run python -m tangle_cli.openapi.codegen \
-  --openapi-url https://api.example/openapi.json \
-  --out src/tangle_api/generated \
-  --model-extension-module my_project.tangle_model_extensions
-```
-
-The default module is applied first. Repeated `--model-extension-module` values are applied in order, and later/downstream modules become leftmost in the generated public class MRO, so they override earlier/default extensions. If two modules export the same extension class name, codegen imports them with deterministic aliases.
-
-Pass an empty string to disable built-in default extensions:
-
-```bash
-uv run python -m tangle_cli.openapi.codegen \
-  --from-snapshot \
-  --model-extension-module ""
-```
+`tangle_cli.models.compose_models(...)` reads those mappings and creates subclasses in the `tangle_cli.models` namespace, e.g. `ComponentSpec(ComponentSpecExtensions, tangle_api.generated.models.ComponentSpec)`, without mutating `tangle_api.generated.models`. The generated operations layer also calls `_response_model(model_name, default)` so `TangleApiClient` can deserialize responses into the CLI-composed classes while the base `GeneratedTangleApiOperations` remains downstream-agnostic.
 
-The same empty-string sentinel can disable built-in `--model-alias` defaults. Built-in aliases keep stable public model names such as `ComponentSpec` even when a backend schema uses names like `ComponentSpecOutput` or `ComponentSpecInput`.
+Downstream projects can use the same pattern in their own namespace: import base classes from `tangle_api.generated.models`, define method/property-only mixins plus a `MODEL_EXTENSIONS` mapping, and compose subclasses locally. Avoid global monkey-patching of `tangle_api.generated.models`.
 
-Extension classes should be importable from their modules and should not import generated model classes. They should be mixins over generated data, not replacements for generated schemas.
+Built-in `--model-alias` defaults still keep stable public model names such as `ComponentSpec` even when a backend schema uses names like `ComponentSpecOutput` or `ComponentSpecInput`.
 
 ## Extending SDK behavior
 

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/__init__.py

@@ -1,9 +1,9 @@
 """tangle-cli public API.
 
-The package import is intentionally lightweight: native static API bindings live
-in ``tangle_api.generated`` and may be supplied by the consumer environment.
-Import ``tangle_cli.client.TangleApiClient`` explicitly when those generated
-bindings are available.
+The package import is intentionally lightweight: static API bindings live in
+``tangle_api.generated`` (included by default in public installs, or supplied by
+source/downstream environments). Import ``tangle_cli.client.TangleApiClient``
+explicitly when generated bindings should be loaded.
 """
 
 from importlib.metadata import PackageNotFoundError

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/api_cli.py

@@ -503,7 +503,8 @@ def _schema_for_current_invocation() -> dict[str, Any] | None:
             raise SystemExit(
                 f"No cached OpenAPI schema for {_normalize_base_url(base_url)}. "
                 "Run `tangle api refresh` with the same --base-url/--auth-header/--header options, "
-                "or install tangle-cli[native] to use the official static schema."
+                "or use a tangle-cli environment with an official or custom tangle-api package "
+                "that provides tangle_api.schema."
             )
         return cached
 
@@ -571,9 +572,12 @@ def _api_tail_requests_help(api_tail: list[str]) -> bool:
 
 def _missing_official_schema_message() -> str:
     return (
-        "Official static Tangle API commands require the native tangle-api "
-        "package because the bundled OpenAPI snapshot lives in tangle_api.schema. "
-        "Install tangle-cli[native], or run `tangle api refresh` and use "
+        "Official static Tangle API commands require a tangle-api package "
+        "because the OpenAPI snapshot lives in tangle_api.schema. Normal "
+        "tangle-cli installs include the official package; custom generated "
+        "API projects should run with a local src/tangle_api package that "
+        "shadows site-packages or install a compatible private tangle-api "
+        "distribution. Otherwise run `tangle api refresh` and use "
         "`--schema-source cache` for cached backend operations."
     )
 

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/cli_helpers.py

@@ -66,8 +66,8 @@ def api_arg_specs(
 class LazyTangleApiClient:
     """Instantiate the generated API client only when a command uses it.
 
-    Importing CLI modules must stay native-free so local-only commands can run
-    without the generated ``tangle_api`` package. This proxy delays importing and
+    Importing CLI modules must not eagerly load generated bindings, so local-only
+    commands can run without importing ``tangle_api``. This proxy delays importing and
     constructing ``TangleApiClient`` until an API method is actually accessed,
     while keeping CLI-friendly error wording in the CLI helper layer.
     """
@@ -85,9 +85,10 @@ class LazyTangleApiClient:
             except ModuleNotFoundError as exc:
                 if exc.name == "tangle_api":
                     raise SystemExit(
-                        "Native generated Tangle API bindings are required for "
-                        f"{self.command_name}. Install tangle-cli[native] or provide "
-                        "a local tangle_api.generated package."
+                        "Generated Tangle API bindings are required for "
+                        f"{self.command_name}. Install the default tangle-cli package "
+                        "with tangle-api, run from a project where local src/tangle_api "
+                        "shadows site-packages, or install a compatible custom tangle-api package."
                     ) from exc
                 raise
 
@@ -97,7 +98,7 @@ class LazyTangleApiClient:
         return self._client
 
     def require_available(self) -> None:
-        """Materialize the client so CLI commands fail before native helper imports."""
+        """Materialize the client so CLI commands fail before helper imports."""
 
         self._get_client()
 

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/client.py

@@ -26,11 +26,13 @@ from .api_transport import (
     log_http_exchange,
     tangle_verbose_enabled,
 )
-from tangle_api.generated.models import ComponentSpec, GetExecutionInfoResponse
 from tangle_api.generated.operations import GeneratedTangleApiOperations
+from . import models as _cli_models
 from .logger import Logger, _null_logger, get_default_logger
 from .models import (
     ComponentInfo,
+    ComponentSpec,
+    GetExecutionInfoResponse,
     GraphExecutionState,
     PipelineRun,
     RunDetails,
@@ -78,6 +80,11 @@ class TangleApiClient(GeneratedTangleApiOperations):
         self.session = session or requests.Session()
         self.include_env_credentials = include_env_credentials
 
+    def _response_model(self, model_name: str, default: Any) -> Any:
+        """Use CLI-composed models for generated operation deserialization."""
+
+        return getattr(_cli_models, model_name, default)
+
     def set_verbose(self, enabled: bool) -> None:
         """Enable or disable request logging."""
 

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/component_publisher.py

@@ -22,7 +22,7 @@ from .handler import TangleCliHandler
 from .logger import Logger
 
 if TYPE_CHECKING:
-    from tangle_api.generated.models import ComponentSpec
+    from tangle_cli.models import ComponentSpec
 
 
 class ProcessingOutcome(str, Enum):
@@ -171,12 +171,12 @@ class ComponentPublisher(TangleCliHandler):
         if self.component_spec_model is not None:
             return self.component_spec_model
         try:
-            from tangle_api.generated.models import ComponentSpec
+            from tangle_cli.models import ComponentSpec
         except ModuleNotFoundError as exc:
             if exc.name == "tangle_api":
                 raise RuntimeError(
                     "Native generated Tangle API bindings are required for component publishing. "
-                    "Install tangle-cli[native] or provide a local tangle_api.generated package."
+                    "Install the default tangle-cli package with tangle-api, run from a project where local src/tangle_api shadows site-packages, or install a compatible custom tangle-api package."
                 ) from exc
             raise
         return ComponentSpec

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/handler.py

@@ -64,7 +64,7 @@ class TangleCliHandler:
             if exc.name == "tangle_api":
                 self.log.error(
                     "❌ Native generated Tangle API bindings are required for Tangle API operations. "
-                    "Install tangle-cli[native] or provide a local tangle_api.generated package."
+                    "Install the default tangle-cli package with tangle-api, run from a project where local src/tangle_api shadows site-packages, or install a compatible custom tangle-api package."
                 )
                 return None
             raise

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/models.py

@@ -11,9 +11,56 @@ from __future__ import annotations
 from dataclasses import asdict, dataclass, field
 from typing import Any
 
-from tangle_api.generated.models import ComponentSpec, GetExecutionInfoResponse
+from tangle_api.generated import models as _generated_models
 
 from .artifacts import ArtifactComponentQuery, ArtifactInfo
+from . import generated_model_extensions as _cli_model_extensions
+
+
+def extend_model(public_name: str, base: type[Any], *mixins: type[Any]) -> type[Any]:
+    """Compose a generated model with downstream mixins in this namespace."""
+
+    if not mixins:
+        return base
+    model = type(public_name, (*mixins, base), {"__module__": __name__})
+    model_rebuild = getattr(model, "model_rebuild", None)
+    if callable(model_rebuild):
+        model_rebuild()
+    return model
+
+
+def compose_models(generated_models_module: Any, *extension_modules: Any) -> dict[str, type[Any]]:
+    """Return generated models composed with MODEL_EXTENSIONS mappings.
+
+    Extension modules declare ``MODEL_EXTENSIONS = {"ModelName": "MixinName"}``.
+    Composition happens in this downstream namespace and never mutates
+    ``tangle_api.generated.models``.
+    """
+
+    composed: dict[str, type[Any]] = {}
+    public_names = getattr(generated_models_module, "__all__", None)
+    if public_names is None:
+        public_names = [
+            name
+            for name, value in vars(generated_models_module).items()
+            if not name.startswith("_") and isinstance(value, type)
+        ]
+    for public_name in public_names:
+        base = getattr(generated_models_module, public_name)
+        mixins: list[type[Any]] = []
+        for module in extension_modules:
+            mapping = getattr(module, "MODEL_EXTENSIONS", {})
+            if not isinstance(mapping, dict):
+                continue
+            mixin_name = mapping.get(public_name)
+            if mixin_name:
+                mixins.append(getattr(module, mixin_name))
+        composed[public_name] = extend_model(public_name, base, *mixins)
+    return composed
+
+
+_COMPOSED_MODELS = compose_models(_generated_models, _cli_model_extensions)
+globals().update(_COMPOSED_MODELS)
 
 
 # ---- Execution / Run dataclasses -------------------------------------------
@@ -296,10 +343,9 @@ class SecretInfo:
 # ---- Components ------------------------------------------------------------
 
 
-# ``ComponentSpec`` is generated from OpenAPI and extended in
-# ``tangle_cli.generated_model_extensions.ComponentSpecExtensions``. Re-export
-# it from this module for compatibility with callers that import domain models
-# from ``tangle_cli.models``.
+# ``ComponentSpec`` is generated from OpenAPI and extended at import time in
+# this module. Re-export it for compatibility with callers that import domain
+# models from ``tangle_cli.models``.
 
 
 @dataclass

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/openapi/codegen.py

@@ -22,9 +22,7 @@ import sys
 import tempfile
 import urllib.parse
 import urllib.request
-from collections import Counter
 from collections.abc import Sequence
-from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
@@ -40,7 +38,6 @@ _REPO_ROOT = Path(__file__).resolve().parents[5]
 _GENERATED_DIR = _REPO_ROOT / "packages" / "tangle-api" / "src" / "tangle_api" / "generated"
 DEFAULT_BACKEND_PATH = _REPO_ROOT / "third_party" / "tangle"
 DEFAULT_OPERATIONS_CLASS_NAME = "GeneratedTangleApiOperations"
-DEFAULT_MODEL_EXTENSION_MODULE = "tangle_cli.generated_model_extensions"
 DEFAULT_MODEL_ALIASES: dict[str, tuple[str, ...]] = {
     "ComponentSpec": (
         "ComponentSpec-Output",
@@ -373,171 +370,63 @@ def _apply_request_body_schema_overrides(
     return output
 
 
-@dataclass(frozen=True)
-class _ModelExtensionRef:
-    """Import reference for one generated model extension class."""
+def generate_runtime() -> str:
+    """Generate the small runtime module used by generated Pydantic models."""
 
-    module_name: str
-    class_name: str
-    alias: str
+    return '''"""Runtime helpers for generated Tangle API model packages."""
 
+from __future__ import annotations
 
-def _model_extension_modules(
-    model_extension_module: str | Sequence[str] | None,
-) -> list[str]:
-    """Return ordered model extension modules, applying defaults first.
+from typing import Any
 
-    ``None`` means the built-in default module. A string or sequence appends
-    downstream modules after the built-in default. The empty-string sentinel
-    disables the default module and is otherwise ignored.
-    """
+from pydantic import BaseModel
 
-    if model_extension_module is None:
-        modules: list[str] = []
-    elif isinstance(model_extension_module, str):
-        modules = [model_extension_module]
-    else:
-        modules = list(model_extension_module)
+try:
+    from pydantic import ConfigDict
+except ImportError:  # pragma: no cover - pydantic v1 fallback
+    ConfigDict = None  # type: ignore[assignment]
 
-    include_default = True
-    if "" in modules:
-        include_default = False
-        modules = [module for module in modules if module != ""]
 
-    ordered = ([DEFAULT_MODEL_EXTENSION_MODULE] if include_default else []) + modules
-    deduped: list[str] = []
-    seen: set[str] = set()
-    for module in ordered:
-        if not module or module in seen:
-            continue
-        seen.add(module)
-        deduped.append(module)
-    return deduped
+class TangleGeneratedModel(BaseModel):
+    """Base for generated response models with dict-like conveniences."""
 
+    if ConfigDict is not None:
+        model_config = ConfigDict(extra="allow", populate_by_name=True)
+    else:  # pragma: no cover - pydantic v1 fallback
+        class Config:
+            extra = "allow"
+            allow_population_by_field_name = True
 
-def _validate_module_name(module_name: str) -> str:
-    parts = module_name.split(".")
-    if not parts or any(not re.fullmatch(r"[A-Za-z_]\w*", part) or keyword.iskeyword(part) for part in parts):
-        raise ValueError(f"Invalid model extension module name: {module_name!r}")
-    return module_name
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.to_dict().get(key, default)
 
+    def __getitem__(self, key: str) -> Any:
+        return self.to_dict()[key]
 
-def _model_extension_mapping(module_name: str) -> dict[str, str]:
-    """Load and validate a MODEL_EXTENSIONS mapping from an extension module."""
+    def to_dict(self) -> dict[str, Any]:
+        if hasattr(self, "model_dump"):
+            return self.model_dump(by_alias=True)
+        return self.dict(by_alias=True)
 
-    module_name = _validate_module_name(module_name)
-    try:
-        module = importlib.import_module(module_name)
-    except Exception as exc:  # pragma: no cover - importlib preserves details
-        raise ValueError(f"Could not import model extension module {module_name!r}: {exc}") from exc
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Any:
+        if hasattr(cls, "model_validate"):
+            return cls.model_validate(data)
+        return cls.parse_obj(data)
 
-    mapping = getattr(module, "MODEL_EXTENSIONS", None)
-    if not isinstance(mapping, dict):
-        raise ValueError(
-            f"Model extension module {module_name!r} must define a MODEL_EXTENSIONS dict"
-        )
 
-    extensions: dict[str, str] = {}
-    for model_name, extension_name in mapping.items():
-        if not isinstance(model_name, str) or not isinstance(extension_name, str):
-            raise ValueError("MODEL_EXTENSIONS keys and values must be strings")
-        _validate_class_name(model_name)
-        _validate_class_name(extension_name)
-        if not hasattr(module, extension_name):
-            raise ValueError(
-                f"Model extension module {module_name!r} does not define {extension_name!r}"
-            )
-        extensions[model_name] = extension_name
-    return extensions
-
-
-def _model_extension_refs(
-    model_extension_module: str | Sequence[str] | None,
-) -> dict[str, list[_ModelExtensionRef]]:
-    """Resolve model extension refs by generated class in configured order."""
-
-    refs_by_model: dict[str, list[_ModelExtensionRef]] = {}
-    raw_refs: list[_ModelExtensionRef] = []
-    for module_name in _model_extension_modules(model_extension_module):
-        for model_name, extension_name in _model_extension_mapping(module_name).items():
-            ref = _ModelExtensionRef(
-                module_name=module_name,
-                class_name=extension_name,
-                alias=extension_name,
-            )
-            refs_by_model.setdefault(model_name, []).append(ref)
-            raw_refs.append(ref)
-
-    unique_ref_keys: list[tuple[str, str]] = []
-    seen_ref_keys: set[tuple[str, str]] = set()
-    for ref in raw_refs:
-        key = (ref.module_name, ref.class_name)
-        if key in seen_ref_keys:
-            continue
-        seen_ref_keys.add(key)
-        unique_ref_keys.append(key)
-
-    class_name_counts = Counter(class_name for _, class_name in unique_ref_keys)
-    alias_counts: Counter[str] = Counter()
-    aliases_by_ref: dict[tuple[str, str], str] = {}
-    for module_name, class_name in unique_ref_keys:
-        if class_name_counts[class_name] == 1:
-            alias = class_name
-        else:
-            alias_base = f"_{_safe_identifier(module_name)}_{class_name}"
-            alias_counts[alias_base] += 1
-            alias = alias_base if alias_counts[alias_base] == 1 else f"{alias_base}_{alias_counts[alias_base]}"
-        aliases_by_ref[(module_name, class_name)] = alias
-
-    aliased: dict[str, list[_ModelExtensionRef]] = {}
-    for model_name, refs in refs_by_model.items():
-        aliased[model_name] = []
-        for ref in refs:
-            aliased[model_name].append(
-                _ModelExtensionRef(
-                    module_name=ref.module_name,
-                    class_name=ref.class_name,
-                    alias=aliases_by_ref[(ref.module_name, ref.class_name)],
-                )
-            )
-    return aliased
-
-
-def _model_extension_import_lines(refs_by_model: dict[str, list[_ModelExtensionRef]]) -> list[str]:
-    """Render deterministic import lines for configured model extensions."""
-
-    refs_by_module: dict[str, list[_ModelExtensionRef]] = {}
-    for refs in refs_by_model.values():
-        for ref in refs:
-            refs_by_module.setdefault(ref.module_name, []).append(ref)
-
-    lines: list[str] = []
-    for module_name, refs in sorted(refs_by_module.items()):
-        imports: list[str] = []
-        seen: set[tuple[str, str]] = set()
-        for ref in sorted(refs, key=lambda item: (item.class_name, item.alias)):
-            key = (ref.class_name, ref.alias)
-            if key in seen:
-                continue
-            seen.add(key)
-            if ref.alias == ref.class_name:
-                imports.append(ref.class_name)
-            else:
-                imports.append(f"{ref.class_name} as {ref.alias}")
-        lines.append(f"from {module_name} import {', '.join(imports)}")
-    return lines
+__all__ = ["TangleGeneratedModel"]
+'''
 
 
 def generate_models(
     schema: dict[str, Any],
-    model_extension_module: str | Sequence[str] | None = None,
     model_aliases: dict[str, Sequence[str] | str] | Sequence[str] | str | None = None,
 ) -> str:
-    """Generate Pydantic model classes and apply configured model extensions."""
+    """Generate plain/base Pydantic model classes."""
 
     raw_schemas = schema.get("components", {}).get("schemas", {}) or {}
     schemas, _ = _apply_model_aliases(raw_schemas, model_aliases)
-    extension_refs = _model_extension_refs(model_extension_module)
     lines: list[str] = [
         '"""Generated Pydantic models for the checked-in Tangle OpenAPI schema.\n\nDo not edit by hand; run ``uv run python -m tangle_cli.openapi.codegen``.\n"""',
         "",
@@ -547,26 +436,10 @@ def generate_models(
         "",
         "from pydantic import Field",
         "",
-        "from tangle_cli.generated_runtime import TangleGeneratedModel",
+        "from tangle_api.generated.runtime import TangleGeneratedModel",
         "",
     ]
 
-    generated_class_names = {
-        _class_name(schema_name)
-        for schema_name, schema_def in schemas.items()
-        if isinstance(schema_def, dict)
-        and (schema_def.get("type") in {"object", None} or "properties" in schema_def)
-    }
-    used_extensions = {
-        class_name: extension_refs[class_name]
-        for class_name in sorted(generated_class_names)
-        if class_name in extension_refs
-    }
-    imports = _model_extension_import_lines(used_extensions)
-    if imports:
-        lines.extend(imports)
-        lines.append("")
-
     exports: list[str] = []
     for schema_name, schema_def in sorted(schemas.items(), key=lambda item: _class_name(item[0])):
         class_name = _class_name(schema_name)
@@ -575,9 +448,7 @@ def generate_models(
             lines.extend([f"{class_name} = Any", ""])
             continue
         properties = schema_def.get("properties") or {}
-        extension_refs_for_class = used_extensions.get(class_name, [])
-        generated_base_name = f"_{class_name}Generated"
-        lines.extend([f"class {generated_base_name}(TangleGeneratedModel):"])
+        lines.append(f"class {class_name}(TangleGeneratedModel):")
         if not properties:
             lines.append("    pass")
         else:
@@ -588,13 +459,6 @@ def generate_models(
                 else:
                     lines.append(f"    {field_name}: Any = None")
         lines.append("")
-        extension_bases = [ref.alias for ref in reversed(extension_refs_for_class)]
-        bases = extension_bases + [generated_base_name]
-        lines.extend([
-            f"class {class_name}({', '.join(bases)}):",
-            "    pass",
-            "",
-        ])
 
     lines.append(f"__all__ = {exports!r}")
     lines.append("")
@@ -727,6 +591,11 @@ def generate_operations(
         "            response_model: Any = None,",
         "        ) -> Any: ...",
         "",
+        "    def _response_model(self, model_name: str, default: Any) -> Any:",
+        "        \"\"\"Return the model class used to deserialize a generated response.\"\"\"",
+        "",
+        "        return default",
+        "",
     ])
 
     used_methods: set[str] = set()
@@ -742,7 +611,7 @@ def generate_operations(
             raw_body_override=bool(operation.operation.get("x-tangle-cli-request-body-schema-override")),
         )
         response_model = _response_model_name(operation.operation, model_ref_aliases)
-        response_arg = response_model if response_model else "None"
+        response_arg = f"self._response_model({response_model!r}, {response_model})" if response_model else "None"
         response_annotation = _response_return_annotation(operation.operation, model_ref_aliases)
         if signature:
             def_line = f"    def {method_name}(self, {signature}) -> {response_annotation}:"
@@ -871,7 +740,6 @@ def generate(
     generated_dir: str | Path = _GENERATED_DIR,
     *,
     operations_class_name: str = DEFAULT_OPERATIONS_CLASS_NAME,
-    model_extension_module: str | Sequence[str] | None = None,
     model_aliases: dict[str, Sequence[str] | str] | Sequence[str] | str | None = None,
     request_body_schemas: dict[str, dict[str, Any]] | Sequence[str] | str | None = None,
 ) -> tuple[dict[str, Any], list[Path]]:
@@ -880,6 +748,7 @@ def generate(
     output_dir.mkdir(parents=True, exist_ok=True)
     generated_files = [
         output_dir / "__init__.py",
+        output_dir / "runtime.py",
         output_dir / "models.py",
         output_dir / "operations.py",
     ]
@@ -887,15 +756,15 @@ def generate(
         '"""Generated OpenAPI support modules."""\n',
         encoding="utf-8",
     )
-    generated_files[1].write_text(
+    generated_files[1].write_text(generate_runtime(), encoding="utf-8")
+    generated_files[2].write_text(
         generate_models(
             schema,
-            model_extension_module=model_extension_module,
             model_aliases=model_aliases,
         ),
         encoding="utf-8",
     )
-    generated_files[2].write_text(
+    generated_files[3].write_text(
         generate_operations(
             schema,
             operations_class_name=operations_class_name,
@@ -961,19 +830,6 @@ def main(argv: list[str] | None = None) -> None:
             f"(default: {DEFAULT_OPERATIONS_CLASS_NAME})."
         ),
     )
-    parser.add_argument(
-        "--model-extension-module",
-        action="append",
-        default=None,
-        help=(
-            "Importable module containing a MODEL_EXTENSIONS mapping from "
-            "generated model class names to extension class names. Repeat to "
-            "compose modules in order; later modules override earlier ones. "
-            "The built-in default module is applied first unless an empty string "
-            "is passed to disable it. "
-            f"(default first: {DEFAULT_MODEL_EXTENSION_MODULE})."
-        ),
-    )
     parser.add_argument(
         "--model-alias",
         action="append",
@@ -1031,7 +887,6 @@ def main(argv: list[str] | None = None) -> None:
     args = parser.parse_args(argv)
     try:
         _validate_class_name(args.operations_class_name)
-        _model_extension_refs(args.model_extension_module)
         _model_alias_mapping(args.model_alias)
         request_body_schema_overrides = _request_body_schema_mapping(args.request_body_schema)
         request_body_schema_overrides.update(_request_body_schema_file_mapping(args.request_body_schema_file))
@@ -1073,7 +928,6 @@ def main(argv: list[str] | None = None) -> None:
         openapi_path,
         args.out,
         operations_class_name=args.operations_class_name,
-        model_extension_module=args.model_extension_module,
         model_aliases=args.model_alias,
         request_body_schemas=request_body_schema_overrides,
     )

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/openapi/parser.py

@@ -49,9 +49,10 @@ def _load_default_openapi_schema() -> dict[str, Any]:
             last_error = exc
     if schema_text is None:
         raise FileNotFoundError(
-            "Default OpenAPI snapshot not found. Install tangle-api, run from a "
-            "source checkout with packages/tangle-api/src/tangle_api/schema/openapi.json, "
-            "or pass --openapi PATH explicitly."
+            "Default OpenAPI snapshot not found. Install the default or a compatible "
+            "custom tangle-api package, run from a source checkout with "
+            "packages/tangle-api/src/tangle_api/schema/openapi.json, or pass "
+            "--openapi PATH explicitly."
         ) from last_error
 
     schema = json.loads(schema_text)

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/pipeline_run_search.py

@@ -28,9 +28,9 @@ _CREATED_AT_WIDTH = 16
 class PageChunk:
     """Metadata for a single page of search results.
 
-    Defined locally to keep this module importable without the native
-    ``tangle-api`` extra; ``tangle_cli.models`` re-exports an equivalent
-    dataclass when native models are available.
+    Defined locally to keep this module importable without loading generated
+    ``tangle-api`` bindings; ``tangle_cli.models`` re-exports an equivalent
+    dataclass when generated models are imported.
     """
 
     rows: list[dict[str, Any]]

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/packages/tangle-cli/src/tangle_cli/quickstart.py

@@ -1,4 +1,4 @@
-"""Native-free quickstart text for the root ``tangle`` CLI."""
+"""Quickstart text for the root ``tangle`` CLI."""
 
 from __future__ import annotations
 
@@ -7,7 +7,7 @@ from textwrap import dedent
 from cyclopts import App
 
 
-app = App(name="quickstart", help="Print a concise native-free guide to the Tangle CLI.")
+app = App(name="quickstart", help="Print a concise guide to the Tangle CLI.")
 
 
 QUICKSTART_TEXT = dedent(
@@ -76,16 +76,15 @@ QUICKSTART_TEXT = dedent(
     dynamic schema discovery, codegen, logging, hydrator/resolver logic, and
     extension hooks.
 
-    tangle_api is the generated/native package: checked-in Pydantic models,
-    endpoint operation methods, and the official OpenAPI snapshot. Local-only
-    SDK commands and this quickstart do not need it. Static API-backed commands
-    need tangle-cli[native] or an equivalent local tangle_api.generated package.
+    tangle_api is the generated package: checked-in Pydantic models,
+    endpoint operation methods, and the official OpenAPI snapshot. Public
+    tangle-cli installs include the matching tangle-api package by default.
+    Codegen/custom API projects can still generate a local src/tangle_api
+    package that shadows site-packages, or provide a compatible private
+    distribution named tangle-api for their environment.
 
-    Generated model extensions use private generated bases plus stable public
-    subclasses, e.g. ComponentSpec(ComponentSpecExtensions,
-    _ComponentSpecGenerated). Extension bases are left of the generated base in
-    the MRO, and downstream --model-extension-module values can add/override
-    behavior while preserving generated fields and stable names.
+    Generated model extensions are composed at runtime in downstream namespaces
+    such as tangle_cli.models, leaving tangle_api generated models plain/leaf.
 
     Discover more
     -------------
@@ -105,6 +104,6 @@ QUICKSTART_TEXT = dedent(
 
 @app.default
 def quickstart() -> None:
-    """Print a concise native-free guide to the Tangle CLI."""
+    """Print a concise guide to the Tangle CLI."""
 
     print(QUICKSTART_TEXT)

{tangle_cli-0.0.1a1 → tangle_cli-0.0.1a3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tangle-cli"
-version = "0.0.1a1"
+version = "0.0.1a3"
 description = "CLI for Tangle, the open-source ML pipeline orchestration platform"
 readme = "README.md"
 authors = [
@@ -18,6 +18,7 @@ dependencies = [
     "pydantic>=2.0",
     "pyyaml>=6.0",
     "requests>=2.32.0",
+    "tangle-api==0.0.1a3",
     "tomli>=2.0; python_version < '3.11'",
 ]
 
@@ -28,10 +29,12 @@ Repository = "https://github.com/TangleML/tangle-cli"
 Issues = "https://github.com/TangleML/tangle-cli/issues"
 
 [project.optional-dependencies]
-native = ["tangle-api==0.1.0"]
+# Compatibility alias: tangle-api is now part of the default public install.
+native = []
 
 [project.scripts]
 tangle = "tangle_cli.cli:main"
+tangle-cli = "tangle_cli.cli:main"
 
 [build-system]
 requires = ["uv_build>=0.11.2,<0.12.0"]

tangle_cli-0.0.1a1/packages/tangle-cli/src/tangle_cli/generated_runtime.py

@@ -1,43 +0,0 @@
-"""Runtime helpers shared by generated Tangle API model packages."""
-
-from __future__ import annotations
-
-from typing import Any
-
-from pydantic import BaseModel
-
-try:
-    from pydantic import ConfigDict
-except ImportError:  # pragma: no cover - pydantic v1 fallback
-    ConfigDict = None  # type: ignore[assignment]
-
-
-class TangleGeneratedModel(BaseModel):
-    """Base for generated response models with dict-like conveniences."""
-
-    if ConfigDict is not None:
-        model_config = ConfigDict(extra="allow", populate_by_name=True)
-    else:  # pragma: no cover - pydantic v1 fallback
-        class Config:
-            extra = "allow"
-            allow_population_by_field_name = True
-
-    def get(self, key: str, default: Any = None) -> Any:
-        return self.to_dict().get(key, default)
-
-    def __getitem__(self, key: str) -> Any:
-        return self.to_dict()[key]
-
-    def to_dict(self) -> dict[str, Any]:
-        if hasattr(self, "model_dump"):
-            return self.model_dump(by_alias=True)
-        return self.dict(by_alias=True)
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> Any:
-        if hasattr(cls, "model_validate"):
-            return cls.model_validate(data)
-        return cls.parse_obj(data)
-
-
-__all__ = ["TangleGeneratedModel"]