iatoolkit 2.74.2__tar.gz → 2.75.0__tar.gz

{iatoolkit-2.74.2/src/iatoolkit.egg-info → iatoolkit-2.75.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iatoolkit
-Version: 2.74.2
+Version: 2.75.0
 Summary: IAToolkit
 Author: Fernando Libedinsky
 License-Expression: MIT

{iatoolkit-2.74.2 → iatoolkit-2.75.0}/src/iatoolkit/__init__.py

@@ -3,7 +3,7 @@
 #
 # IAToolkit is open source software.
 
-__version__ = "2.74.2"
+__version__ = "2.75.0"
 
 # Expose main classes and functions at the top level of the package
 

{iatoolkit-2.74.2 → iatoolkit-2.75.0}/src/iatoolkit/config/system_agents/history_compaction.prompt

@@ -1,6 +1,6 @@
 You compact the older part of a conversation between a person and a company's AI assistant. The conversation is too long for the model's context, so the turns below will be replaced by your summary; the most recent turns stay as they are. The assistant will continue the conversation from your summary alone, so anything you leave out is lost.
 
-Write the summary in the language of the conversation, as Markdown, with these sections (omit a section only when there is nothing for it):
+Write the summary in the language of the conversation, as Markdown, with these sections (omit a section only when there is nothing for it). Write the section headings in that language too, as level-2 headings (`## …`), and do not wrap the summary in a code block:
 
 - **Objective**: what the person is trying to achieve, and how it evolved.
 - **Decisions**: what was agreed, chosen or ruled out, and why when it was said.

{iatoolkit-2.74.2 → iatoolkit-2.75.0}/src/iatoolkit/config/system_prompts/sql_core.prompt

@@ -3,10 +3,13 @@
 - Trabaja siempre con el dialecto SQL indicado para la base seleccionada.
 - Antes de escribir la consulta, revisa el contexto de la base y respeta su marcador
   `dialect=...` (por ejemplo `postgresql` o `mysql`).
-- Usa solo tablas, columnas y relaciones presentes en el schema provisto.
+- El contexto lista las bases y sus tablas, sin columnas. Antes de escribir la
+  consulta, pide con `iat_sql_schema` las columnas de las tablas que vas a usar,
+  todas en una sola llamada. Si una columna no aparece, pide la tabla que la tiene
+  en vez de suponerla.
+- Usa solo tablas de la lista y columnas que `iat_sql_schema` te haya mostrado.
   No inventes columnas ni supongas nombres parecidos.
-- Si la consulta requiere una base especifica, usa `iat_sql_query` con el
-  `database_key` correcto.
+- Ejecuta la consulta con `iat_sql_query` y el `database_key` correcto.
 - Si hay mas de una tabla, subconsulta o CTE, califica las columnas con alias
   en `SELECT`, `JOIN`, `ON`, `WHERE`, `GROUP BY`, `HAVING` y `ORDER BY`.
 - No mezcles sintaxis de distintos dialectos en la misma consulta.

{iatoolkit-2.74.2 → iatoolkit-2.75.0}/src/iatoolkit/config/system_tools_pack.yaml

@@ -220,6 +220,39 @@ tools:
       required:
         - database_key
         - query
+  - function_name: iat_sql_schema
+    description: "Columnas de tablas SQL: antes de escribir una consulta para iat_sql_query, pide aquí las columnas de las tablas que vas a usar. El contexto trae la lista de bases y tablas; esta herramienta trae sus columnas, tipos y descripciones. Pide varias tablas en una sola llamada."
+    routing:
+      force_include_capability: has_sql_sources
+    routing_profile:
+      tags:
+        - sql
+        - database
+        - schema
+        - columns
+      intents:
+        - Get the columns of SQL tables before writing a query.
+        - Inspect the structure of a configured SQL database.
+      examples:
+        - iat_sql_schema(database_key="erp", table_names=["customers", "orders"])
+      cost:
+        penalty: 0.05
+        latency_class: low
+        expensive: false
+    parameters:
+      type: object
+      properties:
+        database_key:
+          type: string
+          description: "Nombre exacto de la base, como aparece en el contexto."
+        table_names:
+          type: array
+          items:
+            type: string
+          description: "Tablas de esa base cuyas columnas necesitas (hasta 10)."
+      required:
+        - database_key
+        - table_names
   - function_name: iat_document_search
     description: Búsqueda semántica sobre documentos internos de la empresa para traer contexto adicional cuando haga falta. No usar si el usuario pide trabajar exclusivamente con un archivo ya adjunto en el turno actual. Usa metadata_filter solo cuando el usuario o el contexto indiquen un filtro de metadata concreto y necesario; si no hace falta, envía null.
     routing:

{iatoolkit-2.74.2 → iatoolkit-2.75.0}/src/iatoolkit/services/company_context_service.py

@@ -181,129 +181,35 @@ class CompanyContextService:
             return False
         return bool(cls._table_name_candidates(table_name) & allowed_tables)
 
+    @property
+    def sql_catalog(self):
+        """What of each SQL source a person sees (BL-017); built here, it reads this service's schema."""
+        if getattr(self, "_sql_catalog", None) is None:
+            from iatoolkit.services.sql_catalog_service import SqlCatalogService
+
+            self._sql_catalog = SqlCatalogService(self, self.sql_source_service, self.sql_service)
+        return self._sql_catalog
+
     def _get_sql_enriched_context(self, company_short_name: str, allowed_databases: List[str] | None = None,
                                   table_filter=None):
         """
-        Generates the SQL context for the LLM using the enriched schema logic.
-        It iterates over configured databases, fetches their enriched structure,
-        and formats it into a prompt-friendly string.
-        """
-        sql_sources = self.sql_source_service.list_sources(company_short_name, include_inactive=False)
-        if not sql_sources:
-            return '', []
-
-        allowed_database_set = {
-            str(database or "").strip()
-            for database in (allowed_databases or [])
-            if str(database or "").strip()
-        }
-        if allowed_databases is not None and not allowed_database_set:
-            return "", []
-
-        context_output = []
-        db_tables=[]
+        The SQL block of the base context: a map of each source the person may
+        query, its tables with a one-line description and no columns (BL-017).
 
-        for source in sql_sources:
-            db_name = source.get('database')
-            if not db_name:
-                continue
-            if allowed_database_set and db_name not in allowed_database_set:
-                continue
-
-            allowed_tables = self._resolve_allowed_tables_for_source(source)
-
-            try:
-                # 1. Get the Enriched Schema (Physical + YAML)
-                enriched_structure = self.get_enriched_database_schema(company_short_name, db_name)
-                if not enriched_structure:
-                    continue
-
-                if allowed_tables is not None:
-                    enriched_structure = {
-                        table_name: table_data
-                        for table_name, table_data in enriched_structure.items()
-                        if self._table_is_allowed(table_name, allowed_tables)
-                    }
-                    if not enriched_structure:
-                        continue
-                if table_filter is not None:
-                    # Tables the person may not query (enterprise's knowledge tables, BL-010).
-                    enriched_structure = {
-                        table_name: table_data
-                        for table_name, table_data in enriched_structure.items()
-                        if table_filter(db_name, table_name)
-                    }
-                    if not enriched_structure:
-                        continue
-
-                # 2. Build Header for this Database
-                dialect = self.sql_service.get_database_dialect(company_short_name, db_name)
-                dialect_suffix = f" [dialect={dialect}]" if dialect else ""
-                db_context = f"### Base SQL (`database_key`): {db_name}{dialect_suffix}\n"
-
-                # Optional: Add DB description from config if available (useful context)
-                db_desc = source.get('description', '')
-                if db_desc:
-                    db_context += f"- Descripcion: {db_desc}\n"
-
-                db_context += (
-                    f"- Usa `iat_sql_query` con `database_key='{db_name}'` para consultar esta base.\n"
-                )
-
-                # 3. Format Tables
-                for table_name, table_data in enriched_structure.items():
-                    table_desc = table_data.get('description', '')
-                    columns = table_data.get('columns', [])
-
-                    # Table Header
-                    table_str = f"\n\n#### Tabla: `{table_name}`"
-                    if table_desc:
-                        table_str += f"\n- Descripcion: {table_desc}"
-
-                    table_str += "\n- Columnas:"
-
-                    # Format Columns
-                    for col in columns:
-                        col_name = col.get('name')
-                        col_type = col.get('type', 'unknown')
-                        col_desc = col.get('description', '')
-                        col_props = col.get('properties') # Nested JSONB structure
-
-                        col_line = f"\n  - `{col_name}` ({col_type})"
-                        if col_desc:
-                            col_line += f": {col_desc}"
-
-                        table_str += col_line
-
-                        # If it has nested properties (JSONB enriched from YAML), format them
-                        if col_props:
-                            table_str += "\n"
-                            table_str += self._format_json_schema(col_props, 2) # Indent level 2
-
-                    db_context += table_str
-
-                    # collect the table names for later use
-                    db_tables.append(
-                        {'db_name': db_name,
-                         'table_name': table_name,
-                         }
-                    )
-
-                context_output.append(db_context)
-
-            except Exception as e:
-                logging.warning(f"Could not generate enriched SQL context for '{db_name}': {e}")
-
-        if not context_output:
-            return "", []
-
-        header = (
-            "## Bases de datos SQL disponibles\n\n"
-            "Estas son las bases SQL que puedes consultar usando `iat_sql_query`. "
-            "El schema a continuacion incluye metadata enriquecida.\n"
+        The columns travel only when a question needs them, through
+        `iat_sql_schema`: the whole schema in the base context was resent on
+        every model call and never compacted (~33k tokens at Maxxa).
+        Returns the block and the (db_name, table_name) pairs it covers.
+        """
+        sources = self.sql_catalog.sources(
+            company_short_name, allowed_databases=allowed_databases, table_filter=table_filter,
         )
-        return header + "\n\n---\n\n".join(context_output), db_tables
-
+        db_tables = [
+            {"db_name": source["database_key"], "table_name": table["name"]}
+            for source in sources
+            for table in source["tables"]
+        ]
+        return self.sql_catalog.render_map(sources), db_tables
 
     def _get_yaml_schema_context(
         self,

{iatoolkit-2.74.2 → iatoolkit-2.75.0}/src/iatoolkit/services/dispatcher_service.py

@@ -33,6 +33,8 @@ class Dispatcher:
         "iat_memory_answer_question",
         "iat_wiki_search",
         "iat_wiki_get_page",
+        # The schema shown is the person's: their sources and tables (BL-017).
+        "iat_sql_schema",
     }
     _tool_execution_hook = None
     # Tool types this module executes itself; an extension cannot take them over.

{iatoolkit-2.74.2 → iatoolkit-2.75.0}/src/iatoolkit/services/history_compaction_service.py

@@ -60,7 +60,7 @@ class HistoryCompactionService:
     #: Parts per compaction: in the background, enough for a history that grew
     #: without compaction (before BL-009) without summarizing forever; in line,
     #: one, because the person is waiting.
-    MAX_CHUNKS = 6
+    MAX_CHUNKS = 4
 
     @inject
     def __init__(self,
@@ -117,7 +117,11 @@ class HistoryCompactionService:
             chunks = chunks[-limit:]
 
         summary = plan.previous_summary
-        for chunk in chunks:
+        for index, chunk in enumerate(chunks):
+            if index and not self._still_matches(company_short_name, user_identifier, model, plan):
+                # Each part costs a model call of minutes; once the history has
+                # changed under the plan, the rest would be summarized for nothing.
+                return {"status": "skipped", "reason": "history_changed", "summarized_parts": index}
             try:
                 response = self.system_agent_runner.run(
                     company,
@@ -276,6 +280,11 @@ class HistoryCompactionService:
     # Applying
     # ------------------------------------------------------------------
 
+    def _still_matches(self, company_short_name: str, user_identifier: str, model: str,
+                       plan: CompactionPlan) -> bool:
+        current = self.session_context.get_context_history(company_short_name, user_identifier, model=model) or []
+        return len(current) >= plan.cut and self._fingerprint(current[:plan.cut]) == plan.prefix_hash
+
     def _apply(self, company_short_name: str, user_identifier: str, model: str,
                plan: CompactionPlan, summary: str) -> dict:
         lock_key = self.history_manager.history_lock_key(company_short_name, user_identifier, model)
@@ -326,18 +335,35 @@ class HistoryCompactionService:
         for key in ("structured_output", "parsed_output"):
             structured = response.get(key)
             if isinstance(structured, dict) and isinstance(structured.get("summary"), str):
-                return structured["summary"].strip()
+                return HistoryCompactionService._unfence(structured["summary"])
         answer = response.get("answer")
         if isinstance(answer, str) and answer.strip():
-            text = answer.strip()
+            text = HistoryCompactionService._unfence(answer)
             try:
                 parsed = json.loads(text)
             except (TypeError, ValueError):
                 return text
             if isinstance(parsed, dict) and isinstance(parsed.get("summary"), str):
-                return parsed["summary"].strip()
+                return HistoryCompactionService._unfence(parsed["summary"])
+            return text
         return ""
 
+    @staticmethod
+    def _unfence(text: str) -> str:
+        """The text without a Markdown code block around it.
+
+        Seen in production: the summary came back as ```summary ... ```, which
+        stored as is would put the whole summary inside a code block.
+        """
+        stripped = str(text or "").strip()
+        if not stripped.startswith("```"):
+            return stripped
+        lines = stripped.split("\n")
+        body = lines[1:]
+        if body and body[-1].strip() == "```":
+            body = body[:-1]
+        return "\n".join(body).strip()
+
     def _count(self, message: Any) -> int:
         try:
             return int(self.llm_client.count_tokens(json.dumps(message, ensure_ascii=False, default=str)))

{iatoolkit-2.74.2 → iatoolkit-2.75.0}/src/iatoolkit/services/llm_client_service.py

@@ -1606,8 +1606,9 @@ class llmClient:
         sql {sql_query}
 
         **INSTRUCCIÓN OBLIGATORIA:**
-        1.  Analiza el error y corrige la sintaxis de la consulta SQL anterior.
-        2.  Llama a la herramienta `{function_name}` **OTRA VEZ**, inmediatamente, con la consulta corregida.
+        1.  Analiza el error y corrige la consulta SQL anterior. Si dice que una columna o una tabla
+            no existe, pide primero sus columnas reales con `iat_sql_schema`; no adivines otro nombre.
+        2.  Llama a la herramienta `{function_name}` **OTRA VEZ** con la consulta corregida.
         3.  **NO** respondas al usuario con este mensaje de error. Tu ÚNICA acción debe ser volver a llamar a la herramienta con la solución.
         """
 

{iatoolkit-2.74.2 → iatoolkit-2.75.0}/src/iatoolkit/services/resource_access_scope.py

@@ -32,7 +32,16 @@ from iatoolkit.common.exceptions import IAToolkitException
 from iatoolkit.repositories.database_manager import DatabaseManager
 from iatoolkit.repositories.models import CollectionType, Company, Document, KnowledgeWiki
 
-SQL_TOOLS = frozenset({"iat_sql_query"})
+SQL_TOOLS = frozenset({"iat_sql_query", "iat_sql_schema"})
+#: Tools whose access follows another tool's (BL-017): whoever may query may read
+#: the schema of what they query, and nobody else. Without this a new tool falls
+#: to the type default and can end up wider or narrower than the one it serves.
+TOOL_ACCESS_ALIASES = {"iat_sql_schema": "iat_sql_query"}
+
+
+def tool_access_key(function_name: str) -> str:
+    """The tool name whose access list decides this tool's access."""
+    return TOOL_ACCESS_ALIASES.get(function_name, function_name)
 COLLECTION_TOOLS = frozenset({"iat_document_search", "iat_document_list", "iat_image_search", "iat_visual_search"})
 DOCUMENT_READ_TOOLS = frozenset({"iat_document_read"})
 WIKI_TOOLS = frozenset({"iat_wiki_search", "iat_wiki_get_page"})
@@ -55,7 +64,7 @@ class ResourceAccessScope:
         """The call's arguments, narrowed to what the person may reach; raises PERMISSION otherwise."""
         if not user_identifier:
             return arguments
-        if not access.can(company_short_name, user_identifier, USE, "tool", function_name):
+        if not access.can(company_short_name, user_identifier, USE, "tool", tool_access_key(function_name)):
             raise _denied(f"No access to the tool '{function_name}'.")
 
         scoped = dict(arguments)

iatoolkit-2.75.0/src/iatoolkit/services/sql_catalog_service.py

@@ -0,0 +1,260 @@
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+"""
+The SQL schema a person can see, in one place (BL-017).
+
+Two levels, as the MCP always worked: a map of each source (its tables, without
+columns) that is cheap enough to travel in every model call, and the columns of
+the tables a question needs, asked for when it needs them (`iat_sql_schema` in
+the chat, `get_sql_schema` over MCP).
+
+Every filter lives here, so the chat and the MCP cannot show different tables to
+the same person: the source must be active, the person must be allowed the
+source (BL-010), the table must be one of the source's `included_tables`, and
+tables holding resources of their own (enterprise's knowledge tables) must pass
+`access.sql_table_filter`.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional
+
+from iatoolkit.common import access
+
+TableFilter = Optional[Callable[[str, str], bool]]
+
+
+class SqlCatalogService:
+    #: Tables one call to `iat_sql_schema` may describe: the columns of a whole
+    #: database in one answer is the cost this service exists to avoid.
+    MAX_TABLES_PER_REQUEST = 10
+    #: One line per table in the map.
+    MAP_DESCRIPTION_MAX_CHARS = 200
+    SCHEMA_TOOL_NAME = "iat_sql_schema"
+    QUERY_TOOL_NAME = "iat_sql_query"
+
+    def __init__(self, company_context_service, sql_source_service, sql_service):
+        # Built by CompanyContextService itself (it owns the enriched schema and
+        # this owns what of it a person sees), so no injector cycle between them.
+        self.company_context_service = company_context_service
+        self.sql_source_service = sql_source_service
+        self.sql_service = sql_service
+
+    # ------------------------------------------------------------------
+    # Scope of a person
+    # ------------------------------------------------------------------
+
+    def person_scope(self, company_short_name: str, user_identifier: str | None) -> tuple[list[str] | None, TableFilter]:
+        """(allowed databases, table filter) for this person; (None, None) when nothing is restricted."""
+        if not user_identifier or not access.Access.registered():
+            return None, None
+        databases = [str(s.get("database") or "") for s in self._active_sources(company_short_name) if s.get("database")]
+        allowed = [d for d in databases
+                   if access.can(company_short_name, user_identifier, access.USE, "sql_source", d)]
+        table_filter = access.sql_table_filter(company_short_name, user_identifier)
+        return (None if len(allowed) == len(databases) else allowed), table_filter
+
+    # ------------------------------------------------------------------
+    # The two levels
+    # ------------------------------------------------------------------
+
+    def sources(self, company_short_name: str, *, allowed_databases: list[str] | None = None,
+                table_filter: TableFilter = None) -> list[dict]:
+        """Each visible source with its visible tables (name, kind, description), no columns."""
+        allowed = self._allowed_set(allowed_databases)
+        if allowed is not None and not allowed:
+            return []
+        items = []
+        for source in self._active_sources(company_short_name):
+            database_key = str(source.get("database") or "").strip()
+            if not database_key or (allowed is not None and database_key not in allowed):
+                continue
+            try:
+                tables = self.visible_schema(company_short_name, database_key, source=source, table_filter=table_filter)
+            except Exception as e:
+                logging.warning(f"Could not read the schema of '{database_key}' for '{company_short_name}': {e}")
+                continue
+            if not tables:
+                continue
+            items.append({
+                "database_key": database_key,
+                "dialect": self._dialect(company_short_name, database_key),
+                "description": str(source.get("description") or "").strip(),
+                "tables": [
+                    {
+                        "name": name,
+                        "object_type": data.get("object_type") or "table",
+                        "description": self._one_line(data.get("description")),
+                    }
+                    for name, data in tables.items()
+                ],
+            })
+        return items
+
+    def describe(self, company_short_name: str, database_key: str, table_names: list[str] | None, *,
+                 allowed_databases: list[str] | None = None, table_filter: TableFilter = None) -> dict:
+        """The columns of the requested tables of one source, or why they cannot be given."""
+        database_key = str(database_key or "").strip()
+        source = self._source(company_short_name, database_key)
+        allowed = self._allowed_set(allowed_databases)
+        if source is None or (allowed is not None and database_key not in allowed):
+            return {"database_key": database_key, "error": "unknown_database",
+                    "available_databases": [s["database_key"] for s in self.sources(
+                        company_short_name, allowed_databases=allowed_databases, table_filter=table_filter)]}
+
+        visible = self.visible_schema(company_short_name, database_key, source=source, table_filter=table_filter)
+        requested = [str(name or "").strip() for name in (table_names or []) if str(name or "").strip()]
+        if not requested:
+            return {"database_key": database_key, "error": "table_names_required",
+                    "available_tables": list(visible.keys())}
+
+        index = {}
+        for name in visible:
+            for candidate in self.company_context_service._table_name_candidates(name):
+                index.setdefault(candidate, name)
+        found: dict[str, dict] = {}
+        unknown: list[str] = []
+        for name in requested:
+            match = next((index[c] for c in self.company_context_service._table_name_candidates(name) if c in index), None)
+            if match is None:
+                unknown.append(name)
+            elif match not in found:
+                found[match] = visible[match]
+
+        omitted = list(found)[self.MAX_TABLES_PER_REQUEST:]
+        for name in omitted:
+            found.pop(name)
+        result = {
+            "database_key": database_key,
+            "dialect": self._dialect(company_short_name, database_key),
+            "tables": found,
+        }
+        if unknown:
+            result["unknown_tables"] = unknown
+            result["available_tables"] = list(visible.keys())
+        if omitted:
+            result["omitted_tables"] = omitted
+        return result
+
+    def visible_schema(self, company_short_name: str, database_key: str, *, source: dict | None = None,
+                       table_filter: TableFilter = None) -> dict:
+        """The enriched schema of one source, narrowed to the tables a person may see."""
+        source = source if source is not None else self._source(company_short_name, database_key)
+        if source is None:
+            return {}
+        ccs = self.company_context_service
+        schema = ccs.get_enriched_database_schema(company_short_name, database_key) or {}
+        included = ccs._resolve_allowed_tables_for_source(source)
+        return {
+            name: data
+            for name, data in schema.items()
+            if ccs._table_is_allowed(name, included)
+            and (table_filter is None or table_filter(database_key, name))
+        }
+
+    # ------------------------------------------------------------------
+    # What the model reads
+    # ------------------------------------------------------------------
+
+    def render_map(self, sources: list[dict]) -> str:
+        if not sources:
+            return ""
+        parts = []
+        for source in sources:
+            dialect = f" [dialect={source['dialect']}]" if source.get("dialect") else ""
+            lines = [f"### Base SQL (`database_key`): {source['database_key']}{dialect}"]
+            if source.get("description"):
+                lines.append(f"- Descripcion: {source['description']}")
+            lines.append("- Tablas:")
+            for table in source.get("tables") or []:
+                kind = " (vista)" if table.get("object_type") == "view" else ""
+                description = f": {table['description']}" if table.get("description") else ""
+                lines.append(f"  - `{table['name']}`{kind}{description}")
+            parts.append("\n".join(lines))
+        header = (
+            "## Bases de datos SQL disponibles\n\n"
+            f"Estas son las bases SQL que puedes consultar, con sus tablas. Antes de escribir una consulta, "
+            f"pide con `{self.SCHEMA_TOOL_NAME}` las columnas de las tablas que vas a usar (varias en una sola "
+            f"llamada); luego consulta con `{self.QUERY_TOOL_NAME}`. Usa solo tablas de esta lista y columnas "
+            f"que `{self.SCHEMA_TOOL_NAME}` te haya mostrado.\n"
+        )
+        return header + "\n\n---\n\n".join(parts)
+
+    def render_tables(self, description: dict) -> str:
+        """`describe`'s answer as the model reads it: the columns of each table, or what to do instead."""
+        database_key = description.get("database_key") or ""
+        error = description.get("error")
+        if error == "unknown_database":
+            available = ", ".join(f"`{d}`" for d in description.get("available_databases") or []) or "(ninguna)"
+            return f"La base `{database_key}` no existe o no tienes acceso. Bases disponibles: {available}."
+        if error == "table_names_required":
+            return (f"Indica en `table_names` las tablas de `{database_key}` que necesitas (hasta "
+                    f"{self.MAX_TABLES_PER_REQUEST}). Tablas: {self._names(description.get('available_tables'))}.")
+
+        dialect = f" [dialect={description['dialect']}]" if description.get("dialect") else ""
+        out = [f"### Base SQL (`database_key`): {database_key}{dialect}"]
+        for table_name, table_data in (description.get("tables") or {}).items():
+            out.append(self._render_table(table_name, table_data))
+        if description.get("unknown_tables"):
+            out.append(
+                f"\nNo existen o no tienes acceso: {self._names(description['unknown_tables'])}. "
+                f"Tablas de `{database_key}`: {self._names(description.get('available_tables'))}."
+            )
+        if description.get("omitted_tables"):
+            out.append(
+                f"\nSe describen hasta {self.MAX_TABLES_PER_REQUEST} tablas por llamada; pide en otra: "
+                f"{self._names(description['omitted_tables'])}."
+            )
+        return "\n".join(out)
+
+    def _render_table(self, table_name: str, table_data: dict) -> str:
+        text = f"\n#### Tabla: `{table_name}`"
+        if table_data.get("description"):
+            text += f"\n- Descripcion: {table_data['description']}"
+        text += "\n- Columnas:"
+        for column in table_data.get("columns") or []:
+            line = f"\n  - `{column.get('name')}` ({column.get('type', 'unknown')})"
+            if column.get("description"):
+                line += f": {column['description']}"
+            text += line
+            if column.get("properties"):
+                text += "\n" + self.company_context_service._format_json_schema(column["properties"], 2)
+        return text
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _active_sources(self, company_short_name: str) -> list[dict]:
+        return self.sql_source_service.list_sources(company_short_name, include_inactive=False) or []
+
+    def _source(self, company_short_name: str, database_key: str) -> dict | None:
+        return next((s for s in self._active_sources(company_short_name)
+                     if str(s.get("database") or "").strip() == database_key), None)
+
+    def _dialect(self, company_short_name: str, database_key: str) -> str:
+        try:
+            return self.sql_service.get_database_dialect(company_short_name, database_key) or ""
+        except Exception:
+            return ""
+
+    @staticmethod
+    def _allowed_set(allowed_databases: list[str] | None) -> set[str] | None:
+        if allowed_databases is None:
+            return None
+        return {str(d or "").strip() for d in allowed_databases if str(d or "").strip()}
+
+    @classmethod
+    def _one_line(cls, description: Any) -> str:
+        text = " ".join(str(description or "").split())
+        if len(text) <= cls.MAP_DESCRIPTION_MAX_CHARS:
+            return text
+        return text[:cls.MAP_DESCRIPTION_MAX_CHARS].rstrip() + "…"
+
+    @staticmethod
+    def _names(names: list[str] | None) -> str:
+        return ", ".join(f"`{n}`" for n in names or []) or "(ninguna)"