cognix-sdk 0.1.0__tar.gz

cognix_sdk-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# CogniX — un repo, un módulo, una versión.
+# Las cinco features viven aquí dentro con su historia (git filter-repo, 2026-07-29).
+# La cabecera anterior decía que cada miembro era un repo aparte: ya no lo es.
+
+# Local / temporales
+.claude/settings.local.json
+.DS_Store
+*.swp
+scratchpad/
+
+# Python — el workspace uv pone UN entorno en la raiz (antes habia uno por feature, y
+# cada .gitignore de miembro lo ignoraba por su cuenta). Son ~5,5 GB: si esto falta,
+# el primer `git add -A` intenta versionar el entorno entero.
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+# Ficheros de trabajo por sesión (encargos cross-repo): locales, no se versionan (§6).
+SSO-NEXT-SESSION.md
+
+# Portal (Fase 1b) — runtime artefacts y config con secretos.
+# El binario, la base de datos de usuarios y la config con admin keys NO se versionan;
+# se versiona portal.example.json como plantilla.
+portal.json
+cognix-portal.db
+*.db
+/cognix-portal
+/cognix-portal.exe
+
+# Portal SPA — dependencias y build.
+web/node_modules/
+web/dist/
+
+# Diagramas de estrategia — el HTML (+ render.sh) son la fuente; el PNG/PDF se regeneran.
+docs/estrategia/**/*.png
+docs/estrategia/**/*.pdf
+
+# Binaries built by the root Taskfile (task build).
+/bin/
+
+# The umbrella binary when built at the repo root by hand (task build uses bin/).
+/cognix
+
+# Compiled example binaries. A 22 MB ELF was tracked in decidix/examples/eino-router,
+# imported with that repo history: it is a build artifact, it is machine-specific, and it
+# dwarfs every source file in the tree.
+decidix/examples/*/eino-router
+
+# Cross-compiled cgx binaries staged for the PyPI wheels (scripts/build-wheels.py).
+/build/

cognix_sdk-0.1.0/LICENSE

@@ -0,0 +1,141 @@
+CogniX Software License Agreement
+Copyright (c) 2026 Carlos Prados. All rights reserved.
+
+This is not open source software. Read this before installing or using it.
+
+1. DEFINITIONS
+
+   "Licensor" means Carlos Prados, the copyright holder.
+
+   "Software" means the `cognix-sdk` Python package, the `cgx` executable distributed
+   with it, and any documentation, examples or files supplied with either.
+
+   "Platform" means the CogniX inference, training and serving products operated or
+   licensed by the Licensor, including any host system into which they are embedded.
+
+   "Bundle" means a directory in the format the Software produces and validates: a
+   manifest, a model file, a feature extractor and its samples.
+
+   "You" means the individual or legal entity exercising the rights granted here.
+
+2. GRANT OF LICENSE
+
+   Subject to Your compliance with this Agreement, the Licensor grants You a
+   non-exclusive, non-transferable, non-sublicensable, revocable, worldwide,
+   royalty-free license to install and use the Software, for Your internal purposes
+   only, in order to:
+
+   (a) create, inspect and validate Bundles intended for deployment on the Platform;
+   (b) evaluate the Software and the Platform, including before entering into any
+       commercial agreement with the Licensor; and
+   (c) develop and test Your own models and feature extractors against the Bundle
+       format.
+
+   No fee is charged for this license. It confers no right to the Platform itself,
+   which is licensed separately.
+
+3. RESTRICTIONS
+
+   You may not, and may not permit any third party to:
+
+   (a) distribute, publish, sell, rent, lease, lend, host or otherwise make the
+       Software available to any third party, in whole or in part, whether alone or
+       bundled with other software;
+   (b) modify, adapt, translate or create derivative works of the Software;
+   (c) reverse engineer, decompile or disassemble the Software, or attempt to derive
+       its source code, except and only to the extent that this restriction is
+       expressly prohibited by applicable law that cannot be waived by agreement (see
+       Section 4);
+   (d) use the Software, or any knowledge of the Bundle format obtained from it, to
+       develop, or to assist any third party in developing, a product or service that
+       competes with the Software or the Platform;
+   (e) implement, or assist any third party in implementing, an inference, scoring or
+       serving system that consumes Bundles, other than the Platform;
+   (f) remove, obscure or alter any copyright, trademark or other proprietary notice
+       in or displayed by the Software; or
+   (g) circumvent any technical measure that limits the functionality of the Software.
+
+   For the avoidance of doubt: models You create remain Yours, and nothing in this
+   Agreement restricts what You do with a model of Your own in any system, provided
+   You do not do so by means of the Software or of a Bundle-consuming implementation
+   prohibited by Section 3(e).
+
+4. MANDATORY LEGAL RIGHTS
+
+   Nothing in this Agreement excludes or limits any right You have under applicable
+   law that cannot be excluded or limited by agreement. In particular, where Directive
+   2009/24/EC of the European Parliament and of the Council, or the national law
+   implementing it, grants You a right to decompile the Software to achieve
+   interoperability with an independently created program, that right applies
+   notwithstanding Section 3(c), on the conditions that Directive lays down.
+
+5. OWNERSHIP
+
+   The Software is licensed, not sold. The Licensor and its suppliers retain all
+   right, title and interest in and to the Software, including all intellectual
+   property rights. All rights not expressly granted in Section 2 are reserved.
+
+6. THIRD-PARTY COMPONENTS
+
+   The `cgx` executable statically links open source components which are licensed to
+   You under their own terms, not under this Agreement. Those terms are reproduced in
+   the accompanying THIRD-PARTY-NOTICES.md file and prevail over this Agreement in
+   respect of those components.
+
+7. FEEDBACK
+
+   If You send the Licensor suggestions, bug reports or other feedback about the
+   Software, the Licensor may use it without restriction or obligation to You. This
+   does not give the Licensor any right in Your models, Your data or Your Bundles.
+
+8. NO SUPPORT
+
+   This Agreement does not oblige the Licensor to provide support, maintenance,
+   updates or new versions of the Software.
+
+9. TERM AND TERMINATION
+
+   This Agreement takes effect when You first install or use the Software and
+   continues until terminated. It terminates automatically, without notice, if You
+   breach any of its terms. On termination You must stop using the Software and delete
+   all copies of it in Your possession. Sections 3, 5, 10, 11 and 12 survive
+   termination.
+
+10. NO WARRANTY
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+    FOR A PARTICULAR PURPOSE, ACCURACY AND NON-INFRINGEMENT. THE SOFTWARE VALIDATES
+    BUNDLES; IT DOES NOT WARRANT THAT ANY MODEL, PREDICTION OR DECISION PRODUCED WITH
+    ITS HELP IS CORRECT, SAFE OR FIT FOR ANY PURPOSE.
+
+11. LIMITATION OF LIABILITY
+
+    TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSOR SHALL NOT BE
+    LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES,
+    OR FOR ANY LOSS OF PROFITS, REVENUE, DATA OR BUSINESS, ARISING OUT OF OR RELATED
+    TO THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE
+    LICENSOR'S TOTAL AGGREGATE LIABILITY UNDER THIS AGREEMENT SHALL NOT EXCEED ONE
+    HUNDRED EUROS (EUR 100).
+
+    Nothing in this Section limits liability for death or personal injury caused by
+    negligence, for fraud, or for any other liability that cannot be limited under
+    applicable law.
+
+12. GOVERNING LAW AND JURISDICTION
+
+    This Agreement is governed by the laws of Spain, without regard to its conflict of
+    law rules. The courts of the city of Madrid, Spain, shall have exclusive
+    jurisdiction over any dispute arising out of or in connection with it, except that
+    the Licensor may seek injunctive relief in any competent court. This Section does
+    not deprive a consumer of the protection of the mandatory rules of the law of the
+    country in which they are resident.
+
+13. ENTIRE AGREEMENT
+
+    This Agreement is the entire agreement between You and the Licensor regarding the
+    Software and supersedes any prior understanding on that subject. If any provision
+    is held unenforceable, it shall be modified to the minimum extent necessary to
+    make it enforceable, and the remaining provisions shall remain in full force.
+
+Contact: carlosprados@users.noreply.github.com

cognix_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: cognix-sdk
+Version: 0.1.0
+Summary: Empaqueta tu modelo como un bundle de CogniX y compruébalo antes de publicarlo
+Project-URL: Homepage, https://github.com/carlosprados/cognix
+Project-URL: Documentation, https://github.com/carlosprados/cognix/blob/main/sdk/README.md
+Project-URL: Source, https://github.com/carlosprados/cognix
+Author: Carlos Prados
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+License-File: THIRD-PARTY-NOTICES.md
+Keywords: inference,iot,mlops,model-packaging,onnx,starlark
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26.0
+Provides-Extra: sklearn
+Requires-Dist: onnx>=1.16.0; extra == 'sklearn'
+Requires-Dist: scikit-learn>=1.5.0; extra == 'sklearn'
+Requires-Dist: skl2onnx>=1.17.0; extra == 'sklearn'
+Description-Content-Type: text/markdown
+
+# cognix-sdk
+
+> Se instala `cognix-sdk` y se importa `cgx`, como `pillow`→`PIL`. En PyPI, `cognix` es
+> de otro proyecto y `cgx` está reservado por alguien más; `cgx` es el identificador que
+> CogniX ya usa en sus API keys (`cgx_<feature>_…`), así que se queda en el módulo y en
+> el binario.
+
+Empaqueta tu modelo como un bundle de CogniX y **compruébalo en tu máquina** antes de
+publicarlo.
+
+```bash
+uv add cognix-sdk
+uv add "cognix-sdk[sklearn]"   # si quieres exportar un modelo de scikit-learn a ONNX
+```
+
+## Qué problema resuelve
+
+El modelo lo entrenas tú, con lo que quieras. Lo que hay que hacer bien es el **artefacto**,
+y ahí hay una trampa que no da ningún error:
+
+> el extractor de features se escribe **dos veces** — tu `featurize()` en Python para
+> entrenar, y `features.star` (Starlark) que evalúa Go en producción. Cuando se separan, el
+> modelo sigue contestando: sólo que **sobre otra entrada**.
+
+No hay excepción, ni traza, ni métrica que baje. Este paquete existe para que eso falle en
+tu portátil.
+
+## Uso
+
+```python
+import cgx
+from cgx import starlark
+import pandas as pd
+from sklearn.linear_model import LogisticRegression
+from sklearn.preprocessing import StandardScaler
+
+# 1. tus datos (exportados con: wolfctl exports download-export --id <uuid> > datos.parquet)
+df = pd.DataFrame([json.loads(r) for r in pd.read_parquet("datos.parquet")["RESULT"]])
+schema = ["current_a", "vibration", "temperature"]
+
+# 2. tu modelo, como lo entrenas siempre
+scaler = StandardScaler().fit(df[schema].to_numpy())
+clf = LogisticRegression(max_iter=1000).fit(scaler.transform(df[schema].to_numpy()), df["fault_label"])
+
+# 3. el artefacto
+onnx = cgx.to_onnx(clf, n_features=len(schema))
+
+b = cgx.Bundle(
+    domain="motor_faults",
+    feature="classix",
+    schema=schema,
+    featurizer=starlark.identity_featurizer(schema),
+    starlark=starlark.identity("motor_faults", schema),
+    onnx_path=onnx,
+    output_names=cgx.onnx.scores_output(onnx),   # el tensor de scores, no `label`
+    output_kind="probabilities",                    # skl2onnx ya las emite normalizadas
+    payloads=df[schema].head(8).to_dict("records"),   # payloads representativos
+    labels=sorted(df["fault_label"].unique()),
+    mean=scaler.mean_.tolist(),
+    std=scaler.scale_.tolist(),
+)
+
+b.check()        # escribe el bundle y lo verifica; levanta BundleError si algo no cuadra
+```
+
+`check()` hace dos cosas, en este orden:
+
+1. **En Python**: que tu `featurize()` devuelva tantos números como features declaras, para
+   cada payload. Un fallo aquí es tuyo y se ve al instante.
+2. **Con el binario `cgx`**, que viene dentro de este paquete: valida el manifest contra el
+   contrato de la feature y corre `verify-parity` — tu Python contra el Starlark real.
+
+El paso 2 lo hace **el binario**, no una reimplementación de Starlark en Python. Un segundo
+intérprete sería una segunda implementación que puede diferir del motor de producción, o
+sea el mismo problema que esto viene a detectar, movido un nivel. Si el binario no está en
+el PATH, `check()` lo dice y **no finge un OK**.
+
+Falta una tercera comprobación, `verify-bundle`, que reproduce el resultado completo
+—clase, probabilidades, puerta OOD— contra una fixture grabada al entrenar. Esa ejecuta el
+modelo, o sea el motor, y vive en el binario `cognix`: si lo tienes en el PATH, `check()`
+lo usa; si no, dice exactamente qué queda sin cubrir. Un bundle traído de fuera casi nunca
+trae esa fixture de todos modos, porque la escribe el trainer de la feature.
+
+Y ya se puede servir:
+
+```bash
+cognix classix serve --bundles dist
+cognix classix infer --bundle dist/motor_faults --json '{"current_a":18.5,"vibration":1.2,"temperature":97.0}'
+```
+
+## Si tu featurización no es la identidad
+
+`starlark.identity()` sólo cubre el caso "cada feature es un campo numérico del payload".
+Para cualquier otra cosa —una razón entre dos campos, un one-hot, una saturación— escribes
+tu `features.star` a mano y se lo pasas en `starlark=`.
+
+⛔ **No hay traducción automática de Python a Starlark, y es deliberado.** Traducir un
+`featurize()` cualquiera leyendo su AST es la funcionalidad que enamora y la que puede
+traducir mal **en silencio** — exactamente la clase de fallo que este SDK existe para cazar.
+`check()` funciona con el extractor que sea, y esa es la garantía que importa.
+
+## Lo que este paquete NO es
+
+**No es un cliente de la API REST de WolfOps**, y no lo será a mano: un wrapper de ~100
+endpoints envejece con cada endpoint nuevo y se convierte en otro sitio donde algo se queda
+fuera en silencio. Para los datos ya tienes dos líneas que no hay que mantener:
+
+```bash
+wolfctl exports download-export --id <uuid> > datos.parquet
+```
+```python
+df = pd.read_parquet("datos.parquet")
+```
+
+Su contrato es el **formato del bundle** (v3), que está versionado y cambia a propósito, no
+una superficie que cambia cada semana.
+
+## Referencia
+
+| | |
+|---|---|
+| `Bundle(...)` | el artefacto: `.manifest()`, `.payload_schema()`, `.save(dir)`, `.check(dir)` |
+| `to_onnx(model, n_features)` | export de scikit-learn con el opset y la salida que espera el motor |
+| `starlark.identity(domain, schema)` | el `features.star` del caso identidad |
+| `starlark.identity_featurizer(schema)` | su gemelo Python, para pasarlo a `featurizer=` |
+
+El bloque de tarea de cada feature (calibración, intervalos conformes, puerta OOD,
+fallbacks) se declara en `extra_manifest=`: es lo específico de cada una y pertenece a la
+feature, no a este paquete.

cognix_sdk-0.1.0/PUBLISHING.md

@@ -0,0 +1,219 @@
+# Publicar el SDK en PyPI
+
+Ya tienes cuenta. Queda **una cosa que solo puedes hacer tú** (autorizar este repo, 5
+minutos) y después publicar es un comando:
+
+```bash
+task sdk:release:test -- 0.1.0.dev1   # ensayo en TestPyPI
+task sdk:release      -- 0.1.0        # de verdad
+```
+
+`scripts/release-sdk.py` comprueba antes todo lo que se puede comprobar en local —árbol
+limpio, rama al día, versión libre en el índice, `go test`, `pytest`, los wheels
+construidos y el wheel **instalado en un venv vacío** verificando un bundle de verdad— y
+solo entonces pregunta. El push del tag es lo que dispara la publicación.
+
+---
+
+## ⛔ Antes de nada: publicar es hacer público el nombre
+
+Un paquete en PyPI es **visible para cualquiera**, con su README, y aparece en buscadores.
+Eso adelanta el disclosure que aplazaste a Q4 2026 por el conflicto con Amplía — el mismo
+motivo por el que el post de julio salió sin nombres.
+
+Por eso nada se publica sin el tag `sdk-v*`: hasta que lo lances, aquí no pasa nada. Para
+probar el flujo completo antes de esa fecha está **TestPyPI**, que es un índice separado,
+no reserva el nombre en el PyPI real y nadie lo mira.
+
+---
+
+## 1. Autorizar este repositorio (Trusted Publishing) — lo único pendiente
+
+En PyPI, en los ajustes de tu **cuenta** — <https://pypi.org/manage/account/publishing/> —,
+formulario **GitHub**, *Add*.
+
+⚠️ Es a nivel de cuenta, no de proyecto: la página de *Your projects → Publishing* solo
+existe para proyectos ya creados, y `cognix-sdk` todavía no existe. Eso es lo que significa
+*pending*: la autorización queda esperando, y el proyecto se crea con la primera
+publicación que la use.
+
+Rellena **exactamente** esto:
+
+| campo | valor |
+|---|---|
+| PyPI Project Name | `cognix-sdk` |
+| Owner | `carlosprados` |
+| Repository name | `cognix` |
+| Workflow name | `release-sdk.yml` |
+| Environment name | `pypi` |
+
+Repite en **TestPyPI** con Environment name = `testpypi`, en
+<https://test.pypi.org/manage/account/publishing/>.
+
+⚠️ **TestPyPI es un sitio distinto con cuentas distintas.** Tu usuario de PyPI no vale
+allí: hay que registrarse aparte (y activar 2FA aparte). No es un entorno de pruebas del
+mismo servicio, es otro índice.
+
+⚠️ Los cinco campos tienen que coincidir carácter a carácter. Si algo no cuadra, el error
+de PyPI es genérico (*"not a trusted publisher"*) y no dice cuál de los cinco falla —
+compáralos uno a uno contra `.github/workflows/release-sdk.yml`.
+
+⚠️ **No crees ningún token de API.** No hace falta ninguno y es el peor activo que puedes
+tener suelto: un token de PyPI filtrado permite subir cualquier versión de tu paquete a
+quien lo tenga. Trusted Publishing es OIDC — PyPI verifica que la petición viene de este
+repositorio y este workflow, y emite un permiso de un solo uso.
+
+### Y los dos entornos de GitHub
+
+En el repo: **Settings → Environments → New environment**, dos, llamados `pypi` y
+`testpypi`. Sin secretos dentro: son solo el nombre que PyPI verifica.
+
+En `pypi`, **Deployment branches and tags → Selected branches and tags**, y una regla de
+tipo **Tag** con el patrón `sdk-v*`. Al PyPI real solo se llega por un tag; un
+`workflow_dispatch` apuntando ahí desde una rama lo bloquea GitHub, no la confianza.
+
+`testpypi` se queda en *No restriction*: el ensayo se lanza con `workflow_dispatch` desde
+una rama, y restringirlo a tags lo dejaría sin poder ejecutarse nunca.
+
+⛔ **No hay revisor humano, y no es un olvido.** *Required reviewers* y las demás
+*deployment protection rules* exigen plan Pro/Team/Enterprise cuando el repositorio es
+privado — comprobado el 2026-08-01 en este repo: `protection_rules: []`, y la sección ni
+aparece en la página. Publicar en PyPI es **irreversible** (una versión no se reemplaza,
+solo se borra, y el número queda quemado), así que lo que hace de red son tres cosas
+automáticas: sin tag `sdk-v*` no se dispara nada, `release-sdk.py` obliga a teclear la
+versión completa tras sus seis comprobaciones, y el workflow verifica que el tag y
+`sdk/pyproject.toml` coinciden antes de construir.
+
+Si algún día el repo se hace público —o sea, en el disclosure— las protection rules pasan
+a estar disponibles gratis: entonces sí, añade el revisor.
+
+---
+
+## 2. El ensayo
+
+```bash
+task sdk:release:test -- 0.1.0.dev1
+```
+
+Lanza el workflow contra TestPyPI. Cuando termine:
+
+```bash
+uv pip install --index-url https://test.pypi.org/simple/ \
+               --extra-index-url https://pypi.org/simple/ cognix-sdk==0.1.0.dev1
+python -c "import cgx; print(cgx.FEATURES)" && cgx version
+```
+
+El `--extra-index-url` hace falta porque TestPyPI no tiene numpy, y sin él la instalación
+falla por algo que no tiene nada que ver con tu paquete.
+
+⚠️ Una versión de TestPyPI tampoco se puede repetir: usa `0.1.0.dev1`, `dev2`… y reserva
+`0.1.0` para el real.
+
+## 3. Publicar
+
+```bash
+task sdk:release -- 0.1.0
+```
+
+Comprueba después:
+
+```bash
+uv pip install cognix-sdk && python -c "import cgx; print(cgx.FEATURES)" && cgx version
+```
+
+---
+
+## Qué se sube, exactamente
+
+**Una sola distribución, `cognix-sdk`**, con nueve artefactos:
+
+| artefacto | para quién |
+|---|---|
+| 4 wheels Linux (`manylinux` y `musllinux`, x86_64 y aarch64) | glibc y Alpine |
+| 2 wheels macOS (arm64, x86_64) | Apple Silicon e Intel |
+| 1 wheel Windows (`win_amd64`) | |
+| 1 wheel `py3-none-any` **sin binario** | cualquier otra plataforma |
+| 1 sdist | quien lo exija |
+
+pip elige siempre el más específico que le encaje. Los siete primeros llevan dentro el
+binario **`cgx`**, que aterriza en el `bin/` del entorno: `pip install cognix-sdk` y `check()`
+funciona sin más pasos. En una plataforma sin wheel propio se instala el puro y el SDK
+dice, en voz alta, qué comprobación no puede hacer — mejor que un `pip install` que falla.
+
+Se compila todo desde un runner: `cgx` es Go sin cgo, así que cross-compilar es una
+variable de entorno. Es la otra razón por la que el binario público no enlaza ONNX
+Runtime — con cgo harían falta siete runners y una copia del runtime nativo por
+plataforma.
+
+### ⛔ El binario que se publica es `cgx`, nunca `cognix`
+
+`cognix` lleva los cinco motores, ONNX Runtime, el control plane y el servidor: **es el
+producto, y es privado** (regla de Charlie, 2026-08-01). `cgx` lleva el *contrato* del
+bundle —los tipos del manifest y su validación, más el featurizador Starlark— y con eso
+cubre `verify-parity`, `bundle inspect` y `schema`.
+
+Lo único que queda fuera es `verify-bundle`, que reproduce predicciones grabadas pasando
+por el modelo: eso **es** el motor. `cgx` declara el comando para rechazarlo con un mensaje
+que explica dónde está, y el SDK usa `cognix` para esa comprobación si lo encuentra en el
+PATH. No es una mutilación: un bundle traído de fuera casi nunca trae esa fixture, porque
+la escribe el trainer de la feature.
+
+El guardarraíl es `cmd/cgx/deps_test.go`, una **lista blanca** de paquetes del repo que el
+binario público puede enlazar. Falla el build nombrando al intruso, y ya cazó uno el primer
+día: `clikit` arrastraba el almacén de API keys (y sqlite) dentro del binario público.
+
+## Versiones
+
+`sdk/pyproject.toml` lleva la versión y **el tag tiene que coincidir**: `sdk-v0.1.0` ↔
+`version = "0.1.0"`. El script lo comprueba en local y el workflow lo vuelve a comprobar.
+
+El contrato del SDK es el **formato del bundle** (v3 hoy), no la API REST:
+
+- **parche** (`0.1.1`) — arreglos, mensajes, validaciones nuevas;
+- **menor** (`0.2.0`) — funcionalidad nueva compatible;
+- **mayor** (`1.0.0`) — cuando el formato del bundle cambie de versión, porque un bundle
+  escrito por el SDK dejaría de cargar en el motor anterior. Es el único cambio que rompe
+  de verdad a un usuario.
+
+## ⛔ El nombre: distribución `cognix-sdk`, módulo `cgx`
+
+```bash
+pip install cognix-sdk   # la distribución
+import cgx               # el módulo
+```
+
+No coinciden a propósito, como `pillow`→`PIL`. Los dos candidatos naturales estaban
+cogidos, y ninguno es reclamable:
+
+> **`cognix` 0.2.5** — *"AI-powered CLI development assistant"*, de Shichiroh.Shigeh.
+> Proyecto **activo**: 0.1.0 en agosto de 2025, 0.2.5 en febrero de 2026.
+> <https://github.com/cognix-dev/cognix>
+>
+> **`cgx`** — registrado en PyPI, **cero versiones publicadas**. Un nombre reservado que
+> nunca se usó, pero ocupado igual.
+
+El módulo se queda en `cgx` porque es el identificador que el producto ya usa (las API
+keys son `cgx_<feature>_<hex>`, el prefijo de issues es `[CGX]`) y porque llamarlo
+`cognix` pondría un directorio `cognix/` en el `site-packages` de quien tenga el otro
+paquete: dos distribuciones escribiendo la misma ruta se sobreescriben y el import
+devuelve el que ganó la carrera.
+
+### ⛔ Cómo se comprueba si un nombre está libre
+
+Con **`https://pypi.org/simple/<nombre>/`** y solo con eso: 200 existe, 404 libre.
+
+| endpoint | por qué NO vale |
+|---|---|
+| `pypi.org/pypi/<n>/json` | devuelve **404 también para un nombre registrado sin releases** — el caso ambiguo, y justo el de `cgx` |
+| `pypi.org/project/<n>/` | tiene un desafío JavaScript delante: **200 siempre**, exista o no |
+
+Se descubrió por las malas: `cgx` se dio por libre con el endpoint JSON y el formulario
+del pending publisher contestó *"This project already exists"*.
+
+⛔ **Y un pending publisher NO reserva el nombre**: medido el 2026-08-01, el índice seguía
+dando 404 después de crearlo. El nombre no es tuyo hasta la primera publicación — con el
+disclosure aplazado, es tiempo expuesto. Si eso llega a preocupar, la salida es publicar
+un `0.0.1` vacío que solo ocupe el nombre, y eso YA es el disclosure.
+
+⚠️ Y **TestPyPI es otro índice con otras cuentas**: que un nombre esté libre allí no dice
+nada del PyPI real.