iatoolkit 2.59.0__tar.gz → 2.60.0__tar.gz

{iatoolkit-2.59.0/src/iatoolkit.egg-info → iatoolkit-2.60.0}/PKG-INFO

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

{iatoolkit-2.59.0 → iatoolkit-2.60.0}/src/iatoolkit/__init__.py

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

{iatoolkit-2.59.0 → iatoolkit-2.60.0}/src/iatoolkit/config/system_tools_pack.yaml

@@ -282,6 +282,93 @@ tools:
           description: "Opcional en la práctica. Usa null cuando no necesites filtrar por metadata. No inventes filtros ni envíes [] por defecto. Ejemplo: [{'key':'doc.type','value':'invoice'},{'key':'chunk.source_type','value':'table'}]."
       required:
         - query
+  - function_name: iat_document_list
+    description: Lista los documentos de una colección de la empresa con su ficha (título, resumen, tipo, vigencia), del más reciente al más antiguo. Úsala para preguntas de catálogo ("¿qué contratos tenemos?", "¿cuál es la lista de precios vigente?", "¿qué hay en la carpeta Comercial?"), no para buscar un dato dentro de los documentos (para eso, `iat_document_search`). Los documentos reemplazados u obsoletos no aparecen salvo que lo pidas.
+    routing:
+      force_include_capability: has_kb_collections
+    routing_profile:
+      tags:
+        - document
+        - catalog
+        - list
+        - knowledge
+      intents:
+        - List the documents of a company collection with their cards.
+        - Find which documents exist of a given type, or which one is valid today.
+      examples:
+        - iat_document_list(collection="comercial", document_type="contrato")
+        - iat_document_list(collection="legal", valid_on="2026-10-14")
+      cost:
+        penalty: 0.05
+        latency_class: low
+        expensive: false
+    parameters:
+      type: object
+      properties:
+        collection:
+          anyOf:
+            - type: string
+            - type: "null"
+          description: Colección a listar (su nombre exacto). null lista todas.
+        document_type:
+          anyOf:
+            - type: string
+            - type: "null"
+          description: Opcional. Tipo de documento según su ficha (ej. contrato, política, lista de precios, procedimiento).
+        text:
+          anyOf:
+            - type: string
+            - type: "null"
+          description: Opcional. Texto a buscar en el nombre, título, resumen o palabras clave de la ficha.
+        valid_on:
+          anyOf:
+            - type: string
+            - type: "null"
+          description: Opcional. Fecha YYYY-MM-DD; deja los documentos vigentes ese día o sin vigencia indicada.
+        include_inactive:
+          type: boolean
+          description: Incluir documentos reemplazados u obsoletos. Por defecto false.
+        limit:
+          type: integer
+          description: Cuántos documentos devolver (máximo 100). Por defecto 30.
+        offset:
+          type: integer
+          description: Desde qué posición seguir (usa next_offset de la respuesta anterior).
+      required:
+        - collection
+  - function_name: iat_document_read
+    description: Lee el texto de un documento de la empresa, completo o por partes, con su ficha. Úsala cuando la respuesta necesite el documento entero (resumirlo, compararlo, revisar todas sus cláusulas) y no solo los fragmentos que trae `iat_document_search`. El document_id viene de `iat_document_search` o `iat_document_list`. Si la respuesta trae has_more=true, sigue con offset=next_offset.
+    routing:
+      force_include_capability: has_kb_collections
+    routing_profile:
+      tags:
+        - document
+        - read
+        - knowledge
+      intents:
+        - Read a whole company document, or a part of it, by id.
+        - Summarize or compare full documents.
+      examples:
+        - iat_document_read(document_id=42)
+        - iat_document_read(document_id=42, offset=20000)
+      cost:
+        penalty: 0.1
+        latency_class: medium
+        expensive: false
+    parameters:
+      type: object
+      properties:
+        document_id:
+          type: integer
+          description: Identificador del documento, devuelto por `iat_document_search` o `iat_document_list`.
+        offset:
+          type: integer
+          description: Desde qué carácter leer. Por defecto 0.
+        limit:
+          type: integer
+          description: Cuántos caracteres leer (máximo 60000). Por defecto 20000.
+      required:
+        - document_id
   - function_name: iat_wiki_search
     description: Busca páginas publicadas dentro de las wikis de conocimiento compartidas por la empresa. Úsala como acelerador cuando necesites encontrar rápidamente una página relevante, pero no como punto de entrada por defecto. Si no conoces un `path` válido, primero llama `iat_wiki_get_page` con `path="/"` para leer el índice raíz de la wiki y seguir sus links exactos. `wiki_key` es el identificador estable de una wiki publicada, por ejemplo `sales`, `ops` o `hr`; úsalo cuando ya sepas en qué wiki buscar y omítelo cuando quieras buscar en todas las wikis publicadas disponibles en esta conexión MCP. Esta tool devuelve candidatos; luego usa `iat_wiki_get_page` para leer la página completa antes de responder.
     routing:

{iatoolkit-2.59.0 → iatoolkit-2.60.0}/src/iatoolkit/core.py

@@ -392,6 +392,7 @@ class IAToolkit:
         from iatoolkit.repositories.profile_repo import ProfileRepo
         from iatoolkit.repositories.llm_query_repo import LLMQueryRepo
         from iatoolkit.repositories.memory_repo import MemoryRepo
+        from iatoolkit.repositories.memory_question_repo import MemoryQuestionRepo
         from iatoolkit.repositories.mcp_token_repo import McpTokenRepo
         from iatoolkit.repositories.sql_dataset_repo import SqlDatasetRepo
         from iatoolkit.repositories.sql_source_repo import SqlSourceRepo
@@ -407,6 +408,7 @@ class IAToolkit:
         binder.bind(ProfileRepo, to=ProfileRepo)
         binder.bind(LLMQueryRepo, to=LLMQueryRepo)
         binder.bind(MemoryRepo, to=MemoryRepo)
+        binder.bind(MemoryQuestionRepo, to=MemoryQuestionRepo)
         binder.bind(McpTokenRepo, to=McpTokenRepo)
         binder.bind(SqlDatasetRepo, to=SqlDatasetRepo)
         binder.bind(SqlSourceRepo, to=SqlSourceRepo)
@@ -436,6 +438,7 @@ class IAToolkit:
         from iatoolkit.services.pdf_service import PdfService
         from iatoolkit.services.mail_service import MailService
         from iatoolkit.services.memory_compiler_service import MemoryCompilerService
+        from iatoolkit.services.memory_question_service import MemoryQuestionService
         from iatoolkit.services.memory_service import MemoryService
         from iatoolkit.services.mcp_token_service import McpTokenService
         from iatoolkit.services.memory_wiki_service import MemoryWikiService
@@ -481,6 +484,7 @@ class IAToolkit:
         binder.bind(MailService, to=MailService)
         binder.bind(MemoryWikiService, to=MemoryWikiService)
         binder.bind(MemoryCompilerService, to=MemoryCompilerService)
+        binder.bind(MemoryQuestionService, to=MemoryQuestionService)
         binder.bind(MemoryService, to=MemoryService)
         binder.bind(McpTokenService, to=McpTokenService)
         binder.bind(ProfileService, to=ProfileService)

iatoolkit-2.60.0/src/iatoolkit/infra/connectors/google_drive_connector.py

@@ -0,0 +1,308 @@
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass, field
+from typing import Iterator, List
+
+from google.oauth2.service_account import Credentials
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+from googleapiclient.http import MediaIoBaseDownload, MediaIoBaseUpload
+
+from iatoolkit.infra.connectors.file_connector import FileConnector
+
+SCOPE_FULL = "https://www.googleapis.com/auth/drive"
+SCOPE_READ_ONLY = "https://www.googleapis.com/auth/drive.readonly"
+
+FOLDER_MIME_TYPE = "application/vnd.google-apps.folder"
+SHORTCUT_MIME_TYPE = "application/vnd.google-apps.shortcut"
+GOOGLE_APPS_PREFIX = "application/vnd.google-apps."
+
+# Google's own formats have no bytes to download: they are exported. Each one
+# goes to a format the document parsers already read.
+EXPORT_FORMATS = {
+    "application/vnd.google-apps.document": (
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document", ".docx"),
+    "application/vnd.google-apps.spreadsheet": (
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", ".xlsx"),
+    "application/vnd.google-apps.presentation": ("application/pdf", ".pdf"),
+}
+
+FILE_FIELDS = "id, name, mimeType, parents, md5Checksum, modifiedTime, size, trashed, headRevisionId"
+
+
+@dataclass(frozen=True)
+class DriveFile:
+    """A file as Drive describes it, with its path below the folder it was found from."""
+    id: str
+    name: str
+    mime_type: str
+    path: str = ""
+    parents: tuple[str, ...] = ()
+    md5_checksum: str | None = None
+    modified_time: str | None = None
+    size: int | None = None
+    trashed: bool = False
+
+    @property
+    def is_folder(self) -> bool:
+        return self.mime_type == FOLDER_MIME_TYPE
+
+    @property
+    def is_shortcut(self) -> bool:
+        return self.mime_type == SHORTCUT_MIME_TYPE
+
+    @property
+    def is_google_native(self) -> bool:
+        return self.mime_type.startswith(GOOGLE_APPS_PREFIX)
+
+    @property
+    def exportable(self) -> bool:
+        return self.mime_type in EXPORT_FORMATS
+
+    @property
+    def fingerprint(self) -> str:
+        """What tells one version of the file from the next: the content hash for
+        uploaded files, the modification time for Google's own formats (they have
+        no md5)."""
+        return str(self.md5_checksum or self.modified_time or "")
+
+    @classmethod
+    def from_api(cls, payload: dict, *, path: str = "") -> "DriveFile":
+        size = payload.get("size")
+        return cls(
+            id=str(payload.get("id") or ""),
+            name=str(payload.get("name") or ""),
+            mime_type=str(payload.get("mimeType") or ""),
+            path=path,
+            parents=tuple(payload.get("parents") or ()),
+            md5_checksum=payload.get("md5Checksum"),
+            modified_time=payload.get("modifiedTime"),
+            size=int(size) if str(size or "").isdigit() else None,
+            trashed=bool(payload.get("trashed")),
+        )
+
+
+@dataclass(frozen=True)
+class DriveChange:
+    file_id: str
+    removed: bool
+    file: DriveFile | None = None
+
+
+@dataclass(frozen=True)
+class DriveChangesPage:
+    changes: list[DriveChange] = field(default_factory=list)
+    next_page_token: str | None = None
+    new_start_page_token: str | None = None
+
+
+class GoogleDriveConnector(FileConnector):
+    PAGE_SIZE = 1000
+
+    def __init__(
+        self,
+        folder_id: str,
+        service_account_path: str = "service_account.json",
+        service_account_info: dict | None = None,
+        read_only: bool = False,
+    ):
+        """
+        Google Drive through a service account.
+
+        :param folder_id: the folder `list_files` lists and `upload_file` writes to.
+        :param read_only: ask only for `drive.readonly` (whoever only reads, such
+            as Memoria's sync, should); the default keeps the full scope that
+            uploads and deletes need.
+        """
+        self.folder_id = folder_id
+        self.service_account_path = service_account_path
+        self.service_account_info = service_account_info
+        self.scopes = [SCOPE_READ_ONLY if read_only else SCOPE_FULL]
+        self.drive_service = self._authenticate()
+
+    def _authenticate(self):
+        if self.service_account_info:
+            credentials = Credentials.from_service_account_info(self.service_account_info, scopes=self.scopes)
+        else:
+            credentials = Credentials.from_service_account_file(self.service_account_path, scopes=self.scopes)
+        return build('drive', 'v3', credentials=credentials, cache_discovery=False)
+
+    @property
+    def service_account_email(self) -> str | None:
+        info = self.service_account_info or {}
+        return str(info.get("client_email") or "").strip() or None
+
+    # --- FileConnector ------------------------------------------------------
+
+    def list_files(self, prefix: str | None = None) -> List[dict]:
+        """
+        Every direct child of the configured folder, as dicts with 'path' (the
+        file id), 'name' and 'metadata'. Follows every page of results: a folder
+        with more than one page used to be cut silently at the first.
+        """
+        return [
+            {
+                "path": item.id,
+                "name": item.name,
+                "metadata": {
+                    "mime_type": item.mime_type,
+                    "md5_checksum": item.md5_checksum,
+                    "modified_time": item.modified_time,
+                    "size": item.size,
+                },
+            }
+            for item in self.list_children(self.folder_id)
+        ]
+
+    def get_file_content(self, file_path: str) -> bytes:
+        """Bytes of a file by id (exported first if it is a Google Docs/Sheets/Slides file)."""
+        content, _, _ = self.download(file_path)
+        return content
+
+    def upload_file(self, file_path: str, content: bytes, content_type: str = None) -> None:
+        """
+        Uploads to the configured folder. Drive addresses folders by id, so
+        `file_path` is used as the file name.
+        """
+        file_metadata = {'name': file_path, 'parents': [self.folder_id]}
+        media = MediaIoBaseUpload(io.BytesIO(content), mimetype=content_type, resumable=True)
+        self.drive_service.files().create(body=file_metadata, media_body=media, fields='id').execute()
+
+    def delete_file(self, file_path: str) -> None:
+        """Deletes by file id; a file that is already gone is not an error."""
+        try:
+            self.drive_service.files().delete(fileId=file_path).execute()
+        except Exception:
+            pass
+
+    def generate_presigned_url(self, file_path: str, expiration: int = 3600) -> str:
+        raise NotImplementedError("not implemented yet")
+
+    # --- Reading a folder tree ---------------------------------------------
+
+    def get_file(self, file_id: str) -> DriveFile | None:
+        """The file or folder, or None when it does not exist or is not shared with this account."""
+        try:
+            payload = self.drive_service.files().get(
+                fileId=file_id,
+                fields=FILE_FIELDS,
+                supportsAllDrives=True,
+            ).execute()
+        except HttpError as exc:
+            if getattr(exc, "status_code", None) in (403, 404) or getattr(getattr(exc, "resp", None), "status", None) in (403, 404):
+                return None
+            raise
+        return DriveFile.from_api(payload)
+
+    def list_children(self, folder_id: str) -> Iterator[DriveFile]:
+        """Direct children of a folder (files, folders and shortcuts), every page."""
+        page_token = None
+        while True:
+            response = self.drive_service.files().list(
+                q=f"'{folder_id}' in parents and trashed=false",
+                fields=f"nextPageToken, files({FILE_FIELDS})",
+                pageSize=self.PAGE_SIZE,
+                pageToken=page_token,
+                supportsAllDrives=True,
+                includeItemsFromAllDrives=True,
+            ).execute()
+            for payload in response.get("files", []):
+                yield DriveFile.from_api(payload)
+            page_token = response.get("nextPageToken")
+            if not page_token:
+                return
+
+    def walk(self, folder_id: str | None = None) -> Iterator[DriveFile]:
+        """
+        Every file below a folder, with its path relative to it ("Contratos/2026").
+
+        Folders are entered, never returned. Shortcuts are skipped: following one
+        would bring in a file from outside the folder that was shared.
+        """
+        root = folder_id or self.folder_id
+        pending = [(root, "")]
+        seen = {root}
+        while pending:
+            current, path = pending.pop(0)
+            for item in self.list_children(current):
+                if item.is_folder:
+                    if item.id not in seen:
+                        seen.add(item.id)
+                        pending.append((item.id, f"{path}/{item.name}".strip("/")))
+                    continue
+                if item.is_shortcut:
+                    continue
+                yield DriveFile(
+                    id=item.id, name=item.name, mime_type=item.mime_type, path=path,
+                    parents=item.parents, md5_checksum=item.md5_checksum,
+                    modified_time=item.modified_time, size=item.size, trashed=item.trashed,
+                )
+
+    def download(self, file_id: str, mime_type: str | None = None) -> tuple[bytes, str | None, str | None]:
+        """
+        The file's bytes, the extension to give it and their MIME type. Google
+        Docs, Sheets and Slides are exported (docx, xlsx, pdf); other Google
+        formats (forms, maps) cannot be read and raise ValueError.
+        """
+        if mime_type is None:
+            meta = self.get_file(file_id)
+            mime_type = meta.mime_type if meta else ""
+        if str(mime_type).startswith(GOOGLE_APPS_PREFIX):
+            export = EXPORT_FORMATS.get(mime_type)
+            if not export:
+                raise ValueError(f"Google format '{mime_type}' cannot be exported")
+            export_mime, extension = export
+            request = self.drive_service.files().export_media(fileId=file_id, mimeType=export_mime)
+            return self._read(request), extension, export_mime
+        request = self.drive_service.files().get_media(fileId=file_id, supportsAllDrives=True)
+        return self._read(request), None, mime_type or None
+
+    @staticmethod
+    def _read(request) -> bytes:
+        buffer = io.BytesIO()
+        downloader = MediaIoBaseDownload(buffer, request)
+        done = False
+        while not done:
+            _, done = downloader.next_chunk()
+        return buffer.getvalue()
+
+    # --- Changes ------------------------------------------------------------
+
+    def get_start_page_token(self) -> str:
+        """Where to start reading changes from: everything after now."""
+        response = self.drive_service.changes().getStartPageToken(supportsAllDrives=True).execute()
+        return str(response.get("startPageToken") or "")
+
+    def list_changes(self, page_token: str) -> DriveChangesPage:
+        """
+        One page of what changed since `page_token`, for everything this account
+        can see. When `new_start_page_token` is set the caller is up to date and
+        stores it; otherwise it keeps reading with `next_page_token`.
+        """
+        response = self.drive_service.changes().list(
+            pageToken=page_token,
+            pageSize=self.PAGE_SIZE,
+            fields=f"nextPageToken, newStartPageToken, changes(fileId, removed, file({FILE_FIELDS}))",
+            supportsAllDrives=True,
+            includeItemsFromAllDrives=True,
+            spaces="drive",
+        ).execute()
+        changes = [
+            DriveChange(
+                file_id=str(change.get("fileId") or ""),
+                removed=bool(change.get("removed")),
+                file=DriveFile.from_api(change["file"]) if isinstance(change.get("file"), dict) else None,
+            )
+            for change in response.get("changes", [])
+        ]
+        return DriveChangesPage(
+            changes=changes,
+            next_page_token=response.get("nextPageToken"),
+            new_start_page_token=response.get("newStartPageToken"),
+        )

iatoolkit-2.60.0/src/iatoolkit/repositories/memory_question_repo.py

@@ -0,0 +1,121 @@
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+from __future__ import annotations
+
+from injector import inject
+from sqlalchemy import desc
+
+from iatoolkit.repositories.database_manager import DatabaseManager
+from iatoolkit.repositories.models import (
+    LLMQuery,
+    MemoryQuestion,
+    MemoryQuestionCandidate,
+    MemoryQuestionScanCursor,
+)
+
+
+class MemoryQuestionRepo:
+    """Memoria's unanswered questions (BL-005, Fase 1) and what the scan reads."""
+
+    @inject
+    def __init__(self, db_manager: DatabaseManager):
+        self.session = db_manager.get_session()
+
+    def commit(self) -> None:
+        try:
+            self.session.commit()
+        except Exception:
+            self.session.rollback()
+            raise
+
+    def rollback(self) -> None:
+        self.session.rollback()
+
+    def add(self, entity):
+        self.session.add(entity)
+        return entity
+
+    # --- questions -------------------------------------------------------------
+
+    def list_questions(self, company_id: int, status: str | None = MemoryQuestion.STATUS_OPEN,
+                       limit: int = 200) -> list[MemoryQuestion]:
+        query = self.session.query(MemoryQuestion).filter(MemoryQuestion.company_id == company_id)
+        if status:
+            query = query.filter(MemoryQuestion.status == status)
+        return (
+            query.order_by(desc(MemoryQuestion.times_asked), desc(MemoryQuestion.last_asked_at), desc(MemoryQuestion.id))
+            .limit(limit)
+            .all()
+        )
+
+    def get_question(self, company_id: int, question_id: int) -> MemoryQuestion | None:
+        return (
+            self.session.query(MemoryQuestion)
+            .filter(MemoryQuestion.company_id == company_id, MemoryQuestion.id == question_id)
+            .first()
+        )
+
+    def count_open(self, company_id: int) -> int:
+        return (
+            self.session.query(MemoryQuestion)
+            .filter(MemoryQuestion.company_id == company_id, MemoryQuestion.status == MemoryQuestion.STATUS_OPEN)
+            .count()
+        )
+
+    # --- what the scan reads ---------------------------------------------------
+
+    def get_cursor(self, company_id: int) -> MemoryQuestionScanCursor:
+        cursor = (
+            self.session.query(MemoryQuestionScanCursor)
+            .filter(MemoryQuestionScanCursor.company_id == company_id)
+            .first()
+        )
+        if cursor is None:
+            cursor = MemoryQuestionScanCursor(company_id=company_id, last_query_id=0)
+            self.session.add(cursor)
+            self.commit()
+        return cursor
+
+    def list_queries_after(self, company_id: int, last_query_id: int, limit: int) -> list[LLMQuery]:
+        return (
+            self.session.query(LLMQuery)
+            .filter(LLMQuery.company_id == company_id, LLMQuery.id > int(last_query_id or 0))
+            .order_by(LLMQuery.id.asc())
+            .limit(limit)
+            .all()
+        )
+
+    def has_queries_after(self, company_id: int, last_query_id: int) -> bool:
+        return (
+            self.session.query(LLMQuery.id)
+            .filter(LLMQuery.company_id == company_id, LLMQuery.id > int(last_query_id or 0))
+            .first()
+            is not None
+        )
+
+    def find_cursor(self, company_id: int) -> MemoryQuestionScanCursor | None:
+        return (
+            self.session.query(MemoryQuestionScanCursor)
+            .filter(MemoryQuestionScanCursor.company_id == company_id)
+            .first()
+        )
+
+    def list_pending_candidates(self, company_id: int, limit: int) -> list[MemoryQuestionCandidate]:
+        return (
+            self.session.query(MemoryQuestionCandidate)
+            .filter(MemoryQuestionCandidate.company_id == company_id, MemoryQuestionCandidate.processed_at.is_(None))
+            .order_by(MemoryQuestionCandidate.id.asc())
+            .limit(limit)
+            .all()
+        )
+
+    def has_pending_candidates(self, company_id: int) -> bool:
+        return (
+            self.session.query(MemoryQuestionCandidate.id)
+            .filter(MemoryQuestionCandidate.company_id == company_id, MemoryQuestionCandidate.processed_at.is_(None))
+            .first()
+            is not None
+        )

{iatoolkit-2.59.0 → iatoolkit-2.60.0}/src/iatoolkit/repositories/models.py

@@ -564,6 +564,68 @@ class MemoryWikiPageSource(Base):
         return {column.key: getattr(self, column.key) for column in class_mapper(self.__class__).columns}
 
 
+class MemoryQuestion(Base):
+    """
+    A question about the company that the AI could not answer (BL-005, Fase 1).
+
+    Written neutrally and grouped: the same question asked again only adds one
+    to `times_asked`. Who asked is never kept; the count is enough to rank them.
+    Answering it saves a normal Memoria capture, attributed to whoever answered.
+    """
+    __tablename__ = "iat_memory_questions"
+
+    STATUS_OPEN = "open"
+    STATUS_ANSWERED = "answered"
+    STATUS_DISMISSED = "dismissed"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    company_id = Column(Integer, ForeignKey(f"{ORM_SCHEMA}.iat_companies.id", ondelete="CASCADE"), nullable=False, index=True)
+    question = Column(Text, nullable=False)
+    topic = Column(String(200), nullable=True)
+    times_asked = Column(Integer, nullable=False, default=1)
+    # How many times each channel brought it: {"chat": 3, "mcp": 1}.
+    channels = Column(JSON_NATIVE, nullable=True)
+    first_asked_at = Column(DateTime, default=datetime.now, nullable=False)
+    last_asked_at = Column(DateTime, default=datetime.now, nullable=False)
+    status = Column(String(16), nullable=False, default=STATUS_OPEN, index=True)
+    answer_text = Column(Text, nullable=True)
+    answer_capture_id = Column(Integer, ForeignKey(f"{ORM_SCHEMA}.iat_memory_captures.id", ondelete="SET NULL"), nullable=True)
+    resolved_by = Column(String, nullable=True)
+    resolved_at = Column(DateTime, nullable=True)
+    created_at = Column(DateTime, default=datetime.now, nullable=False)
+    updated_at = Column(DateTime, default=datetime.now, onupdate=datetime.now, nullable=False)
+
+    def to_dict(self):
+        return {column.key: getattr(self, column.key) for column in class_mapper(self.__class__).columns}
+
+
+class MemoryQuestionCandidate(Base):
+    """
+    A Memoria search that found nothing outside the chat (MCP: Claude, ChatGPT),
+    whose questions never reach `iat_queries`. The next scan classifies it with
+    the chat's turns. Only the text is kept, not who searched.
+    """
+    __tablename__ = "iat_memory_question_candidates"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    company_id = Column(Integer, ForeignKey(f"{ORM_SCHEMA}.iat_companies.id", ondelete="CASCADE"), nullable=False, index=True)
+    query_text = Column(Text, nullable=False)
+    source = Column(String(16), nullable=False, default="mcp")
+    processed_at = Column(DateTime, nullable=True, index=True)
+    created_at = Column(DateTime, default=datetime.now, nullable=False)
+
+
+class MemoryQuestionScanCursor(Base):
+    """Up to which `iat_queries.id` a company's turns were already reviewed for unanswered questions."""
+    __tablename__ = "iat_memory_question_scan_cursors"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    company_id = Column(Integer, ForeignKey(f"{ORM_SCHEMA}.iat_companies.id", ondelete="CASCADE"), nullable=False, unique=True)
+    last_query_id = Column(Integer, nullable=False, default=0)
+    last_scan_at = Column(DateTime, nullable=True)
+    updated_at = Column(DateTime, default=datetime.now, onupdate=datetime.now, nullable=False)
+
+
 #: request_source of the iat_queries row that records a context initialization:
 #: the company context sent once to start a server-side conversation. Its tokens
 #: are billed, but it is not a question, so conversation readers skip it.

{iatoolkit-2.59.0 → iatoolkit-2.60.0}/src/iatoolkit/services/context_builder_service.py

@@ -481,8 +481,10 @@ class ContextBuilderService:
         lines = [
             "## Colecciones documentales disponibles",
             "Usa `iat_document_search` cuando documentos internos de la empresa puedan ayudar a responder al usuario.",
+            "Usa `iat_document_list` para saber qué documentos hay en una colección y `iat_document_read` para leer uno completo.",
             "### Colecciones",
         ]
+        header_lines = len(lines)
 
         for name, description in selected_entries[:20]:
             if description:
@@ -490,7 +492,7 @@ class ContextBuilderService:
             else:
                 lines.append(f"- {name}")
 
-        if len(lines) <= 3:
+        if len(lines) <= header_lines:
             return ""
 
         lines.append(