tai-sql 0.8.2__tar.gz → 0.8.4__tar.gz

{tai_sql-0.8.2 → tai_sql-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tai-sql
-Version: 0.8.2
+Version: 0.8.4
 Summary: SQL database management and code generation tool
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE

{tai_sql-0.8.2 → tai_sql-0.8.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tai-sql"
-version = "0.8.2"
+version = "0.8.4"
 description = "SQL database management and code generation tool"
 license = "LicenseRef-Proprietary"
 license-files = ["LICENSE"]

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/cli/commands/cmd_schema/schemas/auth.py

@@ -154,7 +154,8 @@ class AuthSchema(SchemaTemplate):
                 # se resolvía solo por nombre, así que un padre podía no existir o ser otro rol
                 # homónimo de otro realm. `restrict`: borrar un rol con subroles es un error,
                 # no una cascada que se los lleve (y `set null` vaciaría también `realm_name`).
-                parent: manytoone[Role] = relation(fields=["parent_role_name", "realm_name"], references=["name", "realm_name"], backref="subroles", onDelete="restrict")
+                # `tree=True`: la jerarquía de roles, con consultas en árbol (`find_many(tree_mode=...)`).
+                parent: manytoone[Role] = relation(fields=["parent_role_name", "realm_name"], references=["name", "realm_name"], backref="subroles", onDelete="restrict", tree=True)
 
                 subroles: onetomany[Role]
 

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/cli/commands/cmd_schema/schemas/chatbot.py

@@ -6,8 +6,8 @@ from .base import SchemaTemplate
 
 
 class ChatbotSchema(SchemaTemplate):
-    """Plantilla chatbot: Chat, Mensaje, TokenUsage, TokenUsageParte, ToolCall, Sugerencia, Modelo, Tarifa, Bolsa,
-    LimitePresupuesto y vistas"""
+    """Plantilla chatbot: Chat, Mensaje, TokenUsage, TokenUsageParte, ToolCall, Sugerencia, InformeConversacion, Modelo,
+    Tarifa, Bolsa, LimitePresupuesto y vistas"""
 
     def get_content(self) -> str:
         return dedent(f'''
@@ -57,7 +57,7 @@ class ChatbotSchema(SchemaTemplate):
 
                 id: col[bigint] = column(primary_key=True, autoincrement=True, description='UUID del chat')
                 title: col[str] = column(description='Título de la conversación')
-                username: col[str] = column(description='ID del usuario propietario del chat')
+                username: col[str] = column(index=True, description='ID del usuario propietario del chat')
                 is_active: col[bool] = column(default=True, description='Estado activo del chat')
 
                 visible: col[bool] = column(default=True, index=True, description='Si no, la conversación no se lista')
@@ -70,6 +70,7 @@ class ChatbotSchema(SchemaTemplate):
 
                 messages: onetomany[Mensaje] # Relación one-to-many con la tabla Mensaje
                 token_usage: onetomany[TokenUsage] # El consumo de la conversación, tenga mensaje o no
+                informes: onetomany[InformeConversacion] # Sus informes: los resúmenes que se pidieron de ella
 
 
             class Feedback(Enum):
@@ -93,7 +94,7 @@ class ChatbotSchema(SchemaTemplate):
                 content: col[str] = column(description='Contenido del mensaje')
                 role: col[MessageRole] = column(description='Rol del mensaje (user, assistant, system)')
                 timestamp: col[datetime] = column(default=datetime.now, description='Timestamp del mensaje')
-                feedback: col[Feedback] = column(default=Feedback.GOOD, description='Feedback del mensaje')
+                feedback: col[Feedback | None] = column(description='La valoración del usuario (good o bad); vacía si no la valoró')
                 feedback_comment: col[str | None] = column(description='Comentario adicional del feedback')
                 reasoning: col[str | None] = column(description='Texto de razonamiento del agente antes de usar herramientas')
                 agent_iterations: col[int] = column(default=0, description='Número de iteraciones del agente')
@@ -101,11 +102,12 @@ class ChatbotSchema(SchemaTemplate):
                 model_name: col[str | None] = column(description='Modelo con el que se respondió')
                 provider: col[str | None] = column(description='Proveedor del modelo con el que se respondió')
 
-                chat_id: col[bigint] = column(description='ID del chat al que pertenece el mensaje')
+                chat_id: col[bigint] = column(index=True, description='ID del chat al que pertenece el mensaje')
 
                 token_usage: onetomany[TokenUsage] # Relación one-to-many con la tabla TokenUsage
                 tool_calls: onetomany[ToolCall] # Relación one-to-many con la tabla ToolCall
                 sugerencias: onetomany[Sugerencia] # Lo que se sugiere preguntar tras esta respuesta
+                informes: onetomany[InformeConversacion] # El informe que entrega este mensaje de sistema
 
                 chat: manytoone[Chat] = relation(fields=['chat_id'], references=['id'], backref='messages') # Relación many-to-one con Chat
 
@@ -123,10 +125,10 @@ class ChatbotSchema(SchemaTemplate):
                 prompt_tokens: col[int] = column(default=0, description='Tokens consumidos en el prompt')
                 completion_tokens: col[int] = column(default=0, description='Tokens consumidos en la respuesta')
                 total_tokens: col[int] = column(default=0, description='Total de tokens consumidos')
-                timestamp: col[datetime] = column(default=datetime.now, description='Timestamp del consumo')
+                timestamp: col[datetime] = column(default=datetime.now, index=True, description='Timestamp del consumo')
 
                 username: col[str] = column(index=True, description='Usuario que consumió')
-                message_id: col[bigint | None] = column(description='Mensaje que lo generó; vacío si se borró la conversación')
+                message_id: col[bigint | None] = column(index=True, description='Mensaje que lo generó; vacío si se borró la conversación')
                 chat_id: col[bigint | None] = column(index=True, description='Conversación en la que se consumió; vacío si no es de ninguna')
 
                 tarifa_id: col[bigint | None] = column(index=True, description='Tarifa con la que se valora')
@@ -150,6 +152,10 @@ class ChatbotSchema(SchemaTemplate):
             class ToolCall(Table):
                 """Tabla que almacena las llamadas a herramientas realizadas por el agente durante la generación de respuestas"""
                 __tablename__ = "tool_call"
+                # El call_id es único dentro de su mensaje (el del modelo, no el de la fila): así una llamada de
+                # un sub-agente puede apuntar a la que lo creó. El índice de esta restricción sirve también para
+                # buscar las llamadas de un mensaje, que empieza por message_id
+                __constraints__ = unique_constraint("message_id", "call_id")
 
                 id: col[bigint] = column(primary_key=True, autoincrement=True, description='ID de la llamada a herramienta')
                 tool_name: col[str] = column(description='Nombre de la herramienta invocada')
@@ -157,10 +163,19 @@ class ChatbotSchema(SchemaTemplate):
                 tool_result: col[dict | None] = column(description='Resultado de la herramienta en formato JSON')
                 duration_ms: col[int | None] = column(description='Duración de la ejecución en milisegundos')
                 success: col[bool] = column(default=True, description='Si la llamada fue exitosa')
+                call_id: col[str | None] = column(description='El id de la llamada que hizo el modelo')
+                padre: col[str | None] = column(description='El call_id de la herramienta que creó el sub-agente que hizo esta llamada; vacío en las del agente principal')
                 timestamp: col[datetime] = column(default=datetime.now, description='Timestamp de la llamada')
                 message_id: col[bigint] = column(description='ID del mensaje asociado')
 
                 message: manytoone[Mensaje] = relation(fields=['message_id'], references=['id'], backref='tool_calls') # Relación many-to-one con Mensaje
+                # La llamada que creó el sub-agente que hizo esta: del mismo mensaje, por la clave compuesta
+                # (message_id, padre) → (message_id, call_id). Por el id del modelo y no por el de la fila: las
+                # filas se crean anidadas en el mensaje, y el id de la del padre todavía no existe. Con padre
+                # vacío (las del agente principal) la clave no se comprueba. Borrar una se lleva sus hijas.
+                # `tree=True`: el árbol de llamadas de una respuesta, con consultas en árbol
+                llamada_padre: manytoone[ToolCall] = relation(fields=['message_id', 'padre'], references=['message_id', 'call_id'], backref='hijas', onDelete='cascade', tree=True)
+                hijas: onetomany[ToolCall]
 
 
             class TokenUsageParte(Table):
@@ -191,6 +206,33 @@ class ChatbotSchema(SchemaTemplate):
                 message: manytoone[Mensaje] = relation(fields=['message_id'], references=['id'], backref='sugerencias', onDelete='cascade')
 
 
+            class InformeConversacion(Table):
+                """Tabla con los informes de una conversación: su resumen, redactado por el modelo; se descarga en DOCX o en PDF"""
+                __tablename__ = "informe_conversacion"
+
+                id: col[bigint] = column(primary_key=True, autoincrement=True)
+                extension: col[str] = column(description="'corto', 'medio' o 'largo'")
+                indicaciones: col[str | None] = column(description='Lo que pidió quien lo pidió (centrarse en algo, las tablas…); vacío si nada. No sale en el documento')
+                estado: col[str] = column(index=True, description="'preparando', 'listo' o 'error'")
+                error: col[str | None] = column(description='Por qué no se pudo preparar')
+                titulo: col[str | None] = column(description='El título que le puso el modelo')
+                contenido: col[str | None] = column(description='El informe, en markdown: el documento se pinta al descargarlo')
+                hasta_mensaje_id: col[bigint | None] = column(description='El último mensaje que resume: con el mismo, se reutiliza sin llamar al modelo')
+                mensajes: col[int] = column(default=0, description='Cuántos mensajes resume')
+                compactado: col[bool] = column(default=False, description='Si la conversación no cabía y se resumió por tandas antes de redactarlo')
+                reutilizado_de: col[bigint | None] = column(description='El informe del que se copió el contenido, sin llamar al modelo')
+                model_name: col[str | None] = column(description='Modelo con el que se redactó')
+                provider: col[str | None] = column(description='Proveedor del modelo con el que se redactó')
+                timestamp: col[datetime] = column(default=datetime.now, description='Cuándo se pidió')
+                chat_id: col[bigint] = column(index=True, description='La conversación que resume')
+                message_id: col[bigint | None] = column(index=True, description='El mensaje de sistema que lo entrega; vacío mientras se prepara')
+
+                # `chat` y `message`, como en TokenUsage: los triggers en cascada comparan las relaciones
+                # por su nombre, y estos no repiten el de ningún padre
+                chat: manytoone[Chat] = relation(fields=['chat_id'], references=['id'], backref='informes', onDelete='cascade')
+                message: manytoone[Mensaje] = relation(fields=['message_id'], references=['id'], backref='informes', onDelete='set null')
+
+
             class Modelo(Table):
                 """Tabla que almacena los modelos con los que puede responder el agente"""
                 __tablename__ = "modelo"
@@ -278,6 +320,8 @@ class ChatbotSchema(SchemaTemplate):
                 total_completion_tokens: col[int]
                 total_tokens: col[int]
                 total_cost_eur: col[float]
+                total_cache_read: col[int | None]
+                total_cache_write: col[int | None]
                 chat_count: col[int]
                 message_count: col[int]
 
@@ -295,6 +339,8 @@ class ChatbotSchema(SchemaTemplate):
                 total_completion_tokens: col[int]
                 total_tokens: col[int]
                 coste_eur: col[float]
+                total_cache_read: col[int | None]
+                total_cache_write: col[int | None]
                 message_count: col[int]
 
 
@@ -379,7 +425,7 @@ class ChatbotSchema(SchemaTemplate):
                 content: col[str]
                 # 'good' o 'bad'
                 feedback: col[str]
-                feedback_comment: col[str]
+                feedback_comment: col[str | None]
                 total_duration_ms: col[int | None]
                 model_name: col[str | None]
                 chat_id: col[bigint]
@@ -517,6 +563,10 @@ class ChatbotSchema(SchemaTemplate):
                               + COALESCE(tu.cache_write, 0) * (COALESCE(t.precio_cache_write_eur_millon, t.precio_input_eur_millon) - t.precio_input_eur_millon)
                               + tu.completion_tokens * t.precio_output_eur_millon)
                               * t.margen / 1000000)::numeric, 8))::double precision as total_cost_eur,
+                    -- Lo leído de la caché del proveedor y lo escrito en ella: parte de la entrada. Sin COALESCE: un
+                    -- día o un mes sin ningún apunte que lo diga (anteriores a apuntarlo) queda vacío, no a 0
+                    SUM(tu.cache_read) as total_cache_read,
+                    SUM(tu.cache_write) as total_cache_write,
                     COUNT(DISTINCT COALESCE(tu.chat_id, me.chat_id)) as chat_count
                 FROM token_usage tu
                 JOIN tarifa t ON t.id = tu.tarifa_id
@@ -557,6 +607,8 @@ class ChatbotSchema(SchemaTemplate):
                 COALESCE(co.total_completion_tokens, 0) as total_completion_tokens,
                 COALESCE(co.total_tokens, 0) as total_tokens,
                 COALESCE(co.total_cost_eur, 0) as total_cost_eur,
+                co.total_cache_read,
+                co.total_cache_write,
                 COALESCE(co.chat_count, 0) as chat_count,
                 COALESCE(e.message_count, 0) as message_count
             FROM consumo co
@@ -586,7 +638,11 @@ class ChatbotSchema(SchemaTemplate):
                               + COALESCE(tu.cache_read, 0) * (COALESCE(t.precio_cache_input_eur_millon, t.precio_input_eur_millon) - t.precio_input_eur_millon)
                               + COALESCE(tu.cache_write, 0) * (COALESCE(t.precio_cache_write_eur_millon, t.precio_input_eur_millon) - t.precio_input_eur_millon)
                               + tu.completion_tokens * t.precio_output_eur_millon)
-                              * t.margen / 1000000)::numeric, 8))::double precision as coste_eur
+                              * t.margen / 1000000)::numeric, 8))::double precision as coste_eur,
+                    -- Lo leído de la caché del proveedor y lo escrito en ella: parte de la entrada. Sin COALESCE: un
+                    -- día o un mes sin ningún apunte que lo diga (anteriores a apuntarlo) queda vacío, no a 0
+                    SUM(tu.cache_read) as total_cache_read,
+                    SUM(tu.cache_write) as total_cache_write
                 FROM token_usage tu
                 JOIN tarifa t ON t.id = tu.tarifa_id
                 JOIN modelo m ON m.id = t.modelo_id
@@ -625,6 +681,8 @@ class ChatbotSchema(SchemaTemplate):
                 COALESCE(co.total_completion_tokens, 0) as total_completion_tokens,
                 COALESCE(co.total_tokens, 0) as total_tokens,
                 COALESCE(co.coste_eur, 0) as coste_eur,
+                co.total_cache_read,
+                co.total_cache_write,
                 COALESCE(e.message_count, 0) as message_count
             FROM consumo co
             FULL JOIN enviados e
@@ -716,9 +774,8 @@ class ChatbotSchema(SchemaTemplate):
         ''').rstrip()
 
         valoracion_sql = dedent('''\
-            -- Vista con las respuestas que el usuario valoró con un comentario, con su conversación
-            -- y lo que se apuntó con ellas. Solo las que tienen comentario: la columna feedback nace
-            -- 'good', así que una valoración sin texto no se distingue de un mensaje sin valorar
+            -- Vista con las respuestas que el usuario valoró (con comentario o sin él), con su
+            -- conversación y lo que se apuntó con ellas. Un mensaje sin valorar tiene feedback vacío
             SELECT
                 m.id as message_id,
                 m.timestamp,
@@ -734,8 +791,7 @@ class ChatbotSchema(SchemaTemplate):
             FROM mensaje m
             JOIN chat c ON c.id = m.chat_id
             WHERE m.role = 'asistente'
-              AND m.feedback_comment IS NOT NULL
-              AND trim(m.feedback_comment) <> ''
+              AND m.feedback IS NOT NULL
             ORDER BY m.timestamp DESC;
         ''').rstrip()
 

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/drivers/base.py

@@ -1107,6 +1107,40 @@ class DatabaseDriver(ABC):
             f"WHERE {no_nulos} AND r.{self.quote_identifier(target_columns[0])} IS NULL"
         )
 
+    def orphans_fix_statements(
+        self, table_name: str, columns: Sequence[str],
+        target_table: str, target_columns: Sequence[str],
+        detach_columns: Sequence[str] = (), schema_name: str = None,
+    ) -> Dict[str, Optional[str]]:
+        """
+        Las sentencias que propone `push` cuando una FK nueva tiene filas huérfanas.
+
+        - `delete`: elimina las filas cuyas columnas de FK no encuentran pareja.
+        - `detach`: pone a NULL `detach_columns` en esas mismas filas, que es lo natural
+          en una FK de la tabla consigo misma —la fila pasa a ser una raíz—. `None` si no
+          se pide.
+
+        La pareja se busca por **todas** las columnas de la FK: con una compuesta, mirar
+        solo la primera borraba filas que no son huérfanas. Es SQL estándar (`NOT
+        EXISTS`); el motor que no acepte una subconsulta sobre la misma tabla que modifica
+        —MySQL— lo sobrescribe.
+        """
+        local = self.qualified_table(table_name, schema_name)
+        destino = self.qualified_table(target_table, schema_name)
+        union = ' AND '.join(
+            f"r.{self.quote_identifier(t)} = {local}.{self.quote_identifier(c)}"
+            for c, t in zip(columns, target_columns)
+        )
+        no_nulos = ' AND '.join(
+            f"{self.quote_identifier(c)} IS NOT NULL" for c in columns
+        )
+        condicion = f"{no_nulos} AND NOT EXISTS (SELECT 1 FROM {destino} r WHERE {union})"
+        detach = None
+        if detach_columns:
+            nulos = ', '.join(f"{self.quote_identifier(c)} = NULL" for c in detach_columns)
+            detach = f"UPDATE {local} SET {nulos} WHERE {condicion}"
+        return {'delete': f"DELETE FROM {local} WHERE {condicion}", 'detach': detach}
+
     # ── Tipos ────────────────────────────────────────────────────────────
 
     def is_sequence_default(self, value: str) -> bool:

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/drivers/mysql.py

@@ -508,6 +508,38 @@ class MySQLDriver(DatabaseDriver):
 
     # ── Escritura de datos ───────────────────────────────────────────────
 
+    def orphans_fix_statements(
+        self, table_name: str, columns: Sequence[str],
+        target_table: str, target_columns: Sequence[str],
+        detach_columns: Sequence[str] = (), schema_name: str = None,
+    ) -> Dict[str, Optional[str]]:
+        """
+        Con `LEFT JOIN` y no con `NOT EXISTS`.
+
+        MySQL no deja modificar una tabla con una subconsulta sobre ella misma (error
+        1093), que es justo el caso de una FK de la tabla consigo misma. El `UPDATE` y el
+        `DELETE` de varias tablas sí admiten unir la tabla consigo misma.
+        """
+        local = self.qualified_table(table_name, schema_name)
+        destino = self.qualified_table(target_table, schema_name)
+        union = ' AND '.join(
+            f"r.{self.quote_identifier(t)} = l.{self.quote_identifier(c)}"
+            for c, t in zip(columns, target_columns)
+        )
+        no_nulos = ' AND '.join(
+            f"l.{self.quote_identifier(c)} IS NOT NULL" for c in columns
+        )
+        huerfana = f"r.{self.quote_identifier(target_columns[0])} IS NULL"
+        joined = f"{local} l LEFT JOIN {destino} r ON {union}"
+        detach = None
+        if detach_columns:
+            nulos = ', '.join(f"l.{self.quote_identifier(c)} = NULL" for c in detach_columns)
+            detach = f"UPDATE {joined} SET {nulos} WHERE {no_nulos} AND {huerfana}"
+        return {
+            'delete': f"DELETE l FROM {joined} WHERE {no_nulos} AND {huerfana}",
+            'detach': detach,
+        }
+
     def upsert_statement(self, table, values, conflict_columns, update_columns,
                          returning=()):
         """

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/errors/collector.py

@@ -19,6 +19,11 @@ decir las cinco, y no obligar a arreglarlas de una en una, recompilando entre me
 
     collector.abort_if_errors()               # los presenta todos y sale
 
+Recoge también **avisos**: lo que conviene cambiar sin que impida seguir, como una forma
+del DSL que se va a retirar. Tienen la misma forma que un error —mensaje, solución,
+ubicación, código— y van aparte porque no cuentan para `has_errors()`: un schema con
+avisos se carga, se genera y se sincroniza igual.
+
 Vive aquí y no en `orm/analysis/`, que es donde nació, porque acumular no es un concepto
 del análisis: es la forma general de reportar varios problemas. La prueba es que
 `SafetyChecker` había reimplementado exactamente esto por su cuenta —una lista de
@@ -32,7 +37,7 @@ from __future__ import annotations
 
 from typing import Iterable, List, Optional
 
-from .render import render_diagnostics
+from .render import render_diagnostics, render_warning
 from .types import Diagnostic, ErrorCode
 
 
@@ -50,6 +55,7 @@ class ErrorCollector:
         self.context = context
         self.enable_colors = enable_colors
         self.errors: List[Diagnostic] = []
+        self.warnings: List[Diagnostic] = []
 
     # ── Registro ─────────────────────────────────────────────────────────
 
@@ -81,6 +87,26 @@ class ErrorCollector:
             )
         )
 
+    def add_warning(
+        self,
+        message: str,
+        solution: str,
+        location: Optional[str] = None,
+        code: Optional[ErrorCode] = None,
+    ) -> None:
+        """
+        Anota un aviso: algo que conviene cambiar, pero que no impide seguir.
+
+        Args:
+            message: Qué conviene saber.
+            solution: Qué cambiar. Obligatorio, igual que en un error.
+            location: Fichero, clase o campo donde ocurre.
+            code: Código para buscarlo en la documentación.
+        """
+        self.warnings.append(
+            Diagnostic(message=message, solution=solution, location=location, code=code)
+        )
+
     def extend(self, diagnostics: Iterable[Diagnostic]) -> None:
         """Anota varios problemas ya construidos."""
         self.errors.extend(diagnostics)
@@ -88,6 +114,7 @@ class ErrorCollector:
     def clear(self) -> None:
         """Olvida lo acumulado."""
         self.errors.clear()
+        self.warnings.clear()
 
     # ── Consulta ─────────────────────────────────────────────────────────
 
@@ -99,6 +126,14 @@ class ErrorCollector:
         """Copia de lo acumulado."""
         return self.errors.copy()
 
+    def has_warnings(self) -> bool:
+        """Si hay algún aviso acumulado."""
+        return bool(self.warnings)
+
+    def get_warnings(self) -> List[Diagnostic]:
+        """Copia de los avisos acumulados."""
+        return self.warnings.copy()
+
     # Nota: deliberadamente SIN __len__. Un colector se usa como objeto, no como
     # contenedor, y darle longitud lo vuelve falsy cuando está vacío — que es el estado
     # normal al empezar. El idioma `collector or ErrorCollector()` pasaba entonces a
@@ -112,6 +147,21 @@ class ErrorCollector:
             self.errors, context=self.context, colors=self.enable_colors
         )
 
+    def show_warnings(self) -> None:
+        """Presenta los avisos acumulados, uno detrás de otro."""
+        for warning in self.warnings:
+            where = ' · '.join(
+                p for p in (
+                    self.context, warning.location, warning.code and warning.code.value
+                ) if p
+            )
+            render_warning(
+                warning.message,
+                hint=warning.solution,
+                location=where or None,
+                colors=self.enable_colors,
+            )
+
     def abort_if_errors(self) -> None:
         """
         Si hay problemas, los presenta todos y termina con código 1.

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/errors/render.py

@@ -237,6 +237,11 @@ def render_warning(
         stream: Dónde escribir. Por defecto stderr.
         colors: `False` fuerza texto pelado.
     """
+    # Una solución de varias líneas —un trozo de código que pegar— sigue alineada bajo
+    # el 💡 en vez de volver al margen
+    if hint:
+        hint = hint.replace('\n', '\n      ')
+
     console = _console(stream) if colors else None
 
     if console is None:

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/errors/types.py

@@ -62,6 +62,9 @@ class ErrorCode(str, Enum):
     # Recursos generados
     GENERATION_FAILED = "E030"
 
+    # Avisos: lo que conviene cambiar, sin impedir seguir
+    DEPRECATED = "W001"
+
 
 @dataclass
 class Diagnostic:

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/generators/diagram/README.md

@@ -37,8 +37,10 @@ lado aunque el schema las declarase:
   dibujaba como `STR`, porque el tipo canónico de la columna es el de sus valores.
 - Las **UNIQUE e índices de varias columnas**, que no caben en la fila de una columna. La
   UNIQUE compuesta es además la clave natural del feed.
-- Las **jerarquías** de `column(self_reference=…)`, que no producen `RelationModel`
-  —no hay dos entidades que relacionar— y por eso el árbol no se veía.
+- Las **jerarquías**. La de `relation(..., tree=True)` es una relación más, y su arista se
+  marca como jerarquía. La de `column(self_reference=…)` —deprecada— no produce
+  `RelationModel` —no hay dos entidades que relacionar— y por eso el árbol no se veía:
+  se añade como arista propia.
 - Las **dimensiones** de una columna vectorial, que es lo único que hay que saber de ella.
 
 Cada bloque se apaga con su `include_*`: `views`, `columns`, `relationships`, `triggers`,

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/generators/diagram/builder.py

@@ -12,8 +12,9 @@ un render.
 Tres cosas que el diagrama enseña y que no salen de recorrer las columnas:
 
 - los **enumerados**, que no son entidades del schema pero tipan columnas;
-- las **jerarquías** de `column(self_reference=…)`, que no producen `RelationModel`
-  porque no hay dos entidades que relacionar;
+- las **jerarquías**: la relación con `tree=True` se dibuja como cualquier otra y se marca
+  como jerarquía, y la de `column(self_reference=…)` —deprecada—, que no produce
+  `RelationModel`, se añade como arista propia;
 - las **UNIQUE e índices de varias columnas**, que no caben en la fila de una columna.
 """
 from __future__ import annotations
@@ -95,14 +96,14 @@ class DiagramBuilder:
 
     def entity(self, entity) -> EREntity:
         """Construye una entidad de dibujo a partir de una del modelo lógico."""
-        hierarchy_column = (
-            entity.self_reference.column_name
-            if not entity.is_view and entity.has_self_reference
-            else None
+        hierarchy_columns = (
+            set(entity.hierarchy.pointer_columns)
+            if not entity.is_view and entity.has_hierarchy
+            else set()
         )
 
         columns = [
-            self.column(column, hierarchy_column)
+            self.column(column, hierarchy_columns)
             for column in entity.columns.values()
             if self.include_operative_fields or not column.is_operative
         ]
@@ -140,7 +141,7 @@ class DiagramBuilder:
             query=getattr(entity, 'query', None),
         )
 
-    def column(self, column, hierarchy_column: Optional[str]) -> ERColumn:
+    def column(self, column, hierarchy_columns=frozenset()) -> ERColumn:
         """Traduce una columna, resolviendo ya la etiqueta de su tipo."""
         return ERColumn(
             name=column.name,
@@ -154,7 +155,7 @@ class DiagramBuilder:
             calculated=column.is_calculated,
             description=column.description,
             is_vector=column.is_vector,
-            hierarchy=column.name == hierarchy_column,
+            hierarchy=column.name in hierarchy_columns,
             operative=column.is_operative,
         )
 
@@ -228,14 +229,17 @@ class DiagramBuilder:
         declarada y su inversa implícita), y quedarse con la implícita hace que la
         arista salga siempre del lado "uno".
 
-        Las jerarquías son aparte: `column(self_reference=…)` no produce `RelationModel`
-        —no hay dos entidades que relacionar—, así que sin esto el árbol no se veía en
-        el diagrama por ningún lado.
+        La jerarquía de `relation(..., tree=True)` es una relación más, marcada como
+        jerarquía. La de `column(self_reference=…)` es aparte: no produce `RelationModel`
+        —no hay dos entidades que relacionar—, así que sin esto el árbol no se veía en el
+        diagrama por ningún lado.
         """
         relationships: List[ERRelationship] = []
 
         for table in self.schema.tables.values():
 
+            tree = table.hierarchy.relation if table.has_hierarchy else None
+
             for relation in table.relations.values():
                 if not relation.implicit:
                     continue
@@ -252,10 +256,16 @@ class DiagramBuilder:
                         relationship_type=relation.direction,
                         local_name=relation.name,
                         target_name=relation.backref,
+                        # La inversa de la relación con `tree=True`, que es la que se dibuja
+                        hierarchy=(
+                            tree is not None
+                            and relation.backref == tree
+                            and relation.target == relation.local
+                        ),
                     )
                 )
 
-            if table.has_self_reference:
+            if table.has_hierarchy and table.hierarchy.relation is None:
                 if drawn is not None and table.tablename not in drawn:
                     continue
                 relationships.append(
@@ -263,8 +273,8 @@ class DiagramBuilder:
                         from_table=table.tablename,
                         to_table=table.tablename,
                         relationship_type=RelationshipType.ONE_TO_MANY.value,
-                        local_name=table.self_reference.column_name,
-                        target_name=table.self_reference.references,
+                        local_name=table.hierarchy.parent_columns[0],
+                        target_name=table.hierarchy.key_columns[0],
                         hierarchy=True,
                     )
                 )

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/generators/diagram/generator.py

@@ -54,8 +54,9 @@ class ERDiagramGenerator(BaseGenerator):
       Graphviz ni conexión.
 
     Lo que dibuja, además de tablas, vistas y columnas: los enumerados con sus valores y
-    qué columna los usa, las UNIQUE e índices de varias columnas, las jerarquías de
-    `column(self_reference=…)` y las dimensiones de una columna vectorial.
+    qué columna los usa, las UNIQUE e índices de varias columnas, las jerarquías
+    (`relation(..., tree=True)` y la deprecada `column(self_reference=…)`) y las
+    dimensiones de una columna vectorial.
     """
 
     def __init__(

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/generators/diagram/model.py

@@ -165,8 +165,9 @@ class ERRelationship:
     relationship_type: str
     local_name: str
     target_name: Optional[str]
-    #: `True` cuando la arista es una jerarquía declarada con `column(self_reference=…)`,
-    #: que no produce `RelationModel` y por tanto no llegaba al diagrama.
+    #: `True` cuando la arista es la jerarquía de la tabla: la relación con `tree=True`, o
+    #: la de `column(self_reference=…)`, que no produce `RelationModel` y sin esto no
+    #: llegaba al diagrama.
     hierarchy: bool = False
 
     @property

{tai_sql-0.8.2 → tai_sql-0.8.4}/tai_sql/generators/python_client/__init__.py

@@ -422,9 +422,9 @@ class PythonClientGenerator(BaseGenerator):
             for col in m.get('columns', [])
         )
 
-        # Pre-compute whether any model has self_reference (hierarchy)
+        # Pre-compute whether any model declares a hierarchy
         has_hierarchy = any(
-            m.get('has_self_reference', False)
+            m.get('has_hierarchy', False)
             for m in all_models_data
         )
 
@@ -494,7 +494,7 @@ class PythonClientGenerator(BaseGenerator):
         elif encoders_path.exists():
             encoders_path.unlink()
 
-        # _shared/utils/hierarchy.py — only when self_reference columns exist
+        # _shared/utils/hierarchy.py — only when some table declares a hierarchy
         hierarchy_path = utils_dir / 'hierarchy.py'
         if has_hierarchy:
             hierarchy_template = self.jinja_env.get_template('shared/utils/hierarchy.py.jinja2')