tangle-cli 0.0.1a1__tar.gz → 0.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: tangle-cli
-Version: 0.0.1a1
+Version: 0.1.0
 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.1.0
 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,26 @@ 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.1.0+yourorg` for a `tangle-cli` dependency on `tangle-api==0.1.0`) 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.
+
+## Agent skills
+
+This repo includes the Tangent agent-skill bundle under `skills/tangent/`. The bundle was ported from `tangle-cli-lab` and now treats this repository as the canonical source. It drives the public `tangle` / `tangle-cli` command surface, assumes the default `tangle-cli` install includes `tangle-api`, and keeps relative references (`agents/*.md`, `references/*.md`) self-contained for Pi-style skill loaders. The source distribution includes `skills/**` so downstream source-based consumers can inspect or vendor the skill docs with the release.
 
 ## Quick command examples
 
@@ -229,9 +233,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 +335,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 +366,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.1.0+yourorg` can satisfy a public `==0.1.0` 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 +387,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 +419,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.1.0}/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,26 @@ 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.1.0+yourorg` for a `tangle-cli` dependency on `tangle-api==0.1.0`) 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.
+
+## Agent skills
+
+This repo includes the Tangent agent-skill bundle under `skills/tangent/`. The bundle was ported from `tangle-cli-lab` and now treats this repository as the canonical source. It drives the public `tangle` / `tangle-cli` command surface, assumes the default `tangle-cli` install includes `tangle-api`, and keeps relative references (`agents/*.md`, `references/*.md`) self-contained for Pi-style skill loaders. The source distribution includes `skills/**` so downstream source-based consumers can inspect or vendor the skill docs with the release.
 
 ## Quick command examples
 
@@ -204,9 +208,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 +310,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 +341,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.1.0+yourorg` can satisfy a public `==0.1.0` 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 +362,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 +394,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.1.0}/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.1.0}/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.1.0}/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.1.0}/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.1.0}/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.1.0}/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.1.0}/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