iatoolkit 2.58.2__tar.gz → 2.60.0__tar.gz

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

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

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

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

iatoolkit-2.60.0/src/iatoolkit/config/system_prompts/memory_usage.prompt

@@ -0,0 +1,20 @@
+### Memoria de la empresa
+
+- La empresa tiene una Memoria: páginas con cómo se hacen las cosas aquí
+  (procedimientos, reglas, excepciones, quién decide), escritas a partir de lo
+  que su gente explicó. Cada dato indica quién lo dijo y cuándo.
+- Usa `iat_memory_search` antes de responder cómo se hace algo en la empresa o
+  cuando la respuesta dependa de prácticas internas. Usa `iat_memory_get_page`
+  para leer una página completa cuando lo necesites; si un resultado trae
+  `has_native_files=true` y el contenido del archivo importa, léela antes de
+  responder.
+- Cuando uses la Memoria, menciona de quién y de cuándo es el dato
+  ("según Carmen, marzo 2026"), porque los procesos cambian.
+- Si la Memoria contradice a un documento, muestra las dos versiones con su
+  fuente; no elijas en silencio.
+- Cuando el usuario te explique cómo se hace algo o te corrija ("no, eso se
+  hace así"), ofrécele guardarlo en la Memoria de la empresa. Si acepta o te lo
+  pide ("guarda esto"), avísale que lo verá toda la empresa con su nombre y usa
+  `iat_memory_save`, con el contenido redactado en tono neutro y autocontenido.
+- No guardes en la Memoria preferencias personales, recordatorios ni datos
+  sensibles que no sirvan al procedimiento.

{iatoolkit-2.58.2 → 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:
@@ -372,35 +459,29 @@ tools:
         - wiki_key
         - path
   - function_name: iat_memory_search
-    description: Busca páginas relevantes dentro de la Memoria personal del usuario y retorna contexto compilado. Incluye la señal `has_native_files` cuando una memoria tiene archivos fuente que pueden adjuntarse nativamente al modelo. Debe usarse antes de responder preguntas sobre cosas guardadas, notas previas, memoria del usuario, continuidad entre sesiones o "lo que hablamos/guardé antes".
+    description: Busca en la Memoria de la empresa, el conocimiento de cómo se hacen las cosas en esta empresa que su gente fue guardando (procedimientos, reglas, excepciones, quién decide, correcciones a documentos). Devuelve páginas con título, resumen y fuentes. Incluye la señal `has_native_files` cuando una página tiene archivos fuente que pueden adjuntarse nativamente al modelo. Úsala antes de responder cómo se hace algo en la empresa, o cuando la pregunta dependa de prácticas internas que podrían no estar en los documentos.
     routing:
       force_include_capability: has_user_memory
     routing_profile:
       tags:
         - memory
-        - personal_context
-        - notes
-        - saved_notes
+        - company_memory
+        - know_how
+        - procedures
+        - internal_practices
+        - corrections
         - saved_content
-        - plans
-        - ideas
-        - work_in_progress
-        - continuity
-        - weekly_focus
         - wiki
       intents:
-        - Search the user's personal memory pages for relevant context.
-        - Retrieve compiled personal notes, saved chat context, and remembered plans or ideas.
-        - Retrieve what the user was planning, working on, or wanted to implement.
-        - Search saved personal context about ideas, tasks, plans, priorities, and previous chat notes.
-        - Use this before answering questions about what the user saved, discussed, planned, or was working on earlier.
+        - Search the company memory for how things are done here.
+        - Retrieve internal procedures, rules, exceptions and who decides, as people in the company explained them.
+        - Check whether people corrected or completed what a company document says.
+        - Use this before answering how something is done in this company.
       examples:
-        - iat_memory_search(query="ideas sobre onboarding", limit=5)
-        - iat_memory_search(query="lo que guardé del cliente acme", limit=3)
-        - iat_memory_search(query="qué tengo pensado para implementar esta semana en iatoolkit", limit=5)
-        - iat_memory_search(query="en qué estoy trabajando ahora", limit=5)
-        - iat_memory_search(query="qué ideas guardé sobre agentes y memorias", limit=5)
-        - iat_memory_search(query="what was I planning to implement this week", limit=5)
+        - iat_memory_search(query="cómo se emite una nota de crédito", limit=5)
+        - iat_memory_search(query="despachos a regiones los viernes", limit=3)
+        - iat_memory_search(query="quién aprueba descuentos sobre 10%", limit=5)
+        - iat_memory_search(query="plazo real de pago de clientes grandes", limit=5)
       cost:
         penalty: 0.08
         latency_class: medium
@@ -410,7 +491,7 @@ tools:
       properties:
         query:
           type: string
-          description: Texto que describe lo que deseas recuperar desde Memoria.
+          description: Texto que describe lo que deseas recuperar desde la Memoria de la empresa.
         limit:
           type: integer
           description: Cantidad máxima de páginas a recuperar.
@@ -420,18 +501,18 @@ tools:
         - query
         - limit
   - function_name: iat_memory_get_page
-    description: Recupera una página completa de la Memoria personal del usuario, incluyendo resumen, decisiones, próximos pasos y fuentes. Si la página proviene de capturas con archivos adjuntos compatibles, esos archivos pueden quedar adjuntos nativamente al turno actual del modelo para inspección directa; en ese caso no hace falta pedir permiso para abrir un access_url temporal. Si `iat_memory_search` devuelve `has_native_files=true` y la respuesta depende del contenido del archivo, debes llamar esta tool antes de responder.
+    description: Recupera una página completa de la Memoria de la empresa, en markdown, con autor y fecha de cada dato y sus fuentes. Si la página proviene de capturas con archivos adjuntos compatibles, esos archivos pueden quedar adjuntos nativamente al turno actual del modelo para inspección directa; en ese caso no hace falta pedir permiso para abrir un access_url temporal. Si `iat_memory_search` devuelve `has_native_files=true` y la respuesta depende del contenido del archivo, debes llamar esta tool antes de responder.
     routing:
       force_include_capability: has_user_memory
     routing_profile:
       tags:
         - memory
+        - company_memory
         - page
-        - compiled_context
         - wiki
       intents:
-        - Open a compiled memory page by id.
-        - Read the full content of a personal memory page before answering.
+        - Open a company memory page by id.
+        - Read the full content of a company memory page before answering.
       examples:
         - iat_memory_get_page(page_id=12)
       cost:
@@ -443,9 +524,49 @@ tools:
       properties:
         page_id:
           type: integer
-          description: Identificador de la página de Memoria a recuperar.
+          description: Identificador de la página de la Memoria de la empresa, devuelto por `iat_memory_search`.
       required:
         - page_id
+  - function_name: iat_memory_save
+    description: Guarda en la Memoria de la empresa algo que el usuario explicó sobre cómo se hacen las cosas en la empresa (un procedimiento, una regla, una excepción, quién decide) o una corrección a lo que dice un documento o a una respuesta tuya. Lo verá TODA la empresa, con el nombre del usuario y la fecha, y se publica de inmediato. Úsala solo cuando el usuario pida guardarlo ("guarda esto", "que lo sepa la empresa") o acepte cuando le ofreces guardarlo tras corregirte. Antes de llamarla, dile al usuario que lo verá toda la empresa. Redacta `content` en tono neutro e impersonal, con solo el conocimiento útil, sin datos personales ni sensibles que no sirvan al procedimiento. No la uses para preferencias o recordatorios personales.
+    # Publishes to the whole company: simulated when an evaluation replays an
+    # agent, and marked as a write for MCP clients so they ask the user first.
+    execution_config:
+      side_effects: true
+      destructive: false
+    routing:
+      force_include_capability: has_user_memory
+    routing_profile:
+      tags:
+        - memory
+        - company_memory
+        - save
+        - capture
+        - know_how
+        - corrections
+      intents:
+        - Save what the user explained about how things are done in the company.
+        - Save a correction the user made to a document or to an answer.
+        - Use only when the user asks to save it or accepts the offer to save it.
+      examples:
+        - iat_memory_save(content="Al cliente Transportes Sur no se le despacha los viernes; la bodega cierra temprano ese día.", title="Despachos a Transportes Sur")
+        - iat_memory_save(content="Las notas de crédito las aprueba Andrea Rojas; si no está, la gerencia.", title="Aprobación de notas de crédito")
+      cost:
+        penalty: 0.1
+        latency_class: medium
+        expensive: false
+    parameters:
+      type: object
+      properties:
+        content:
+          type: string
+          description: El conocimiento a guardar, redactado en tono neutro, completo y autocontenido (debe entenderse sin la conversación).
+        title:
+          type: string
+          description: Título corto del tema, por ejemplo "Notas de crédito".
+      required:
+        - content
+        - title
   - function_name: iat_image_search
     description: Busca imágenes en la base de conocimiento visual de la empresa usando una descripción de texto. Útil cuando el usuario pide 'ver' algo, 'muéstrame una foto de...', o busca gráficos y diagramas.
     routing:

{iatoolkit-2.58.2 → 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
@@ -399,9 +400,7 @@ class IAToolkit:
         from iatoolkit.repositories.filesystem_asset_repository import FileSystemAssetRepository
         from iatoolkit.repositories.env_secret_provider import EnvSecretProvider
         from iatoolkit.common.interfaces.memory_compilation_trigger import MemoryCompilationTrigger
-        from iatoolkit.common.interfaces.memory_lint_trigger import MemoryLintTrigger
         from iatoolkit.services.noop_memory_compilation_trigger import NoopMemoryCompilationTrigger
-        from iatoolkit.services.noop_memory_lint_trigger import NoopMemoryLintTrigger
         from iatoolkit.services.memory_lookup_policy_service import MemoryLookupPolicyService
 
         binder.bind(ApiKeyRepo, to=ApiKeyRepo)
@@ -409,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)
@@ -423,8 +423,6 @@ class IAToolkit:
             binder.bind(SecretProvider, to=EnvSecretProvider)
         if not is_bound(self._injector, MemoryCompilationTrigger):
             binder.bind(MemoryCompilationTrigger, to=NoopMemoryCompilationTrigger)
-        if not is_bound(self._injector, MemoryLintTrigger):
-            binder.bind(MemoryLintTrigger, to=NoopMemoryLintTrigger)
         binder.bind(MemoryLookupPolicyService, to=MemoryLookupPolicyService)
 
     def _bind_services(self, binder: Binder):
@@ -440,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
@@ -485,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"),
+        )