iatoolkit 2.66.0__tar.gz → 2.68.0__tar.gz

{iatoolkit-2.66.0/src/iatoolkit.egg-info → iatoolkit-2.68.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iatoolkit
-Version: 2.66.0
+Version: 2.68.0
 Summary: IAToolkit
 Author: Fernando Libedinsky
 License-Expression: MIT
@@ -242,6 +242,7 @@ Perfect for developers, small teams, single-business use cases, and experimentat
 
 ## 📚 Documentation
 
+- 🐳 **[Docker installation](docker/README.md)** – Community Edition with PostgreSQL, Redis and populated Northwind data
 - 🚀 **[Quickstart](docs/quickstart.md)** – Set up your environment and run the project
 - ☁️ **[Deployment Guide](docs/deployment_guide.md)** – Production deployment instructions
 - 🏗️ **[Companies & Components](docs/companies_and_components.md)** – how Company modules work

{iatoolkit-2.66.0 → iatoolkit-2.68.0}/readme.md

@@ -151,6 +151,7 @@ Perfect for developers, small teams, single-business use cases, and experimentat
 
 ## 📚 Documentation
 
+- 🐳 **[Docker installation](docker/README.md)** – Community Edition with PostgreSQL, Redis and populated Northwind data
 - 🚀 **[Quickstart](docs/quickstart.md)** – Set up your environment and run the project
 - ☁️ **[Deployment Guide](docs/deployment_guide.md)** – Production deployment instructions
 - 🏗️ **[Companies & Components](docs/companies_and_components.md)** – how Company modules work

{iatoolkit-2.66.0 → iatoolkit-2.68.0}/src/iatoolkit/__init__.py

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

iatoolkit-2.68.0/src/iatoolkit/common/memory_tools.py

@@ -0,0 +1,25 @@
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+"""What "used the Memoria" means, in one place (Fase 2 of the Memoria architecture review).
+
+Before, five modules each kept their own list of Memoria tools, so the hourly
+question review, Impacto and the prompts counted different things.
+"""
+
+# Looking for knowledge: a page search or a document search.
+SEARCH_TOOLS = frozenset({"iat_memory_search", "iat_document_search"})
+# Reading what a search found.
+READ_TOOLS = frozenset({"iat_memory_get_page", "iat_document_read", "iat_document_list"})
+# Every tool whose use is a use of the company's knowledge (usage events, Impacto).
+KNOWLEDGE_TOOLS = SEARCH_TOOLS | READ_TOOLS
+
+PAGE_SEARCH_TOOL = "iat_memory_search"
+PAGE_READ_TOOL = "iat_memory_get_page"
+DOCUMENT_SEARCH_TOOL = "iat_document_search"
+DOCUMENT_READ_TOOL = "iat_document_read"
+
+CHANNEL_CHAT = "chat"
+CHANNEL_MCP = "mcp"

iatoolkit-2.68.0/src/iatoolkit/config/system_agents/memory_meeting_ingest.prompt

@@ -0,0 +1,38 @@
+You maintain the company's Memory: a wiki of how things are actually done in this company (procedures, rules, exceptions, who decides). It is written from what its people explain and from the company's own documents.
+
+A meeting transcript was loaded into Memory (SOURCE). You receive it in parts; this is part {{ part.index }} of {{ part.total }} (PART). Bring into the wiki what the meeting decided about how things are done here.
+
+What to take:
+
+- Decisions that were made ("from now on, discounts over 10% need the manager"), with who decided when the transcript says so.
+- Procedures, rules, deadlines and amounts that were agreed or explained, and who is responsible for what.
+- Not the conversation itself: no greetings, small talk, opinions that led nowhere, ideas that were only discussed, or who said what along the way.
+- Nothing personal or sensitive about the people in the meeting (health, salaries, performance, private matters), even if it was said.
+- A transcript is spoken language and may have recognition errors: write the knowledge clearly, and when a name, number or term is unclear, leave it out rather than guess.
+- An action item ("Juan will send the price list on Friday") is not knowledge on its own; keep it only when it reveals how something is done or who is responsible for it.
+
+How to write the pages:
+
+- Update one of the CANDIDATE_PAGES when the part belongs to its subject; create a new page when none covers it (check PAGE_INDEX first so you do not duplicate a page). One part may touch several pages; return each one.
+- When you update, return the COMPLETE new page: keep everything already on it, word for word, including people's attributions. Add the new facts in the section where they belong.
+- When this part says something different from what the page already says, keep both statements with their attributions and make the difference explicit; never delete what someone else said. Also list each contradiction in `conflicts`. A meeting that changes a rule is a contradiction worth showing.
+- Attribute every fact you add to the meeting: ({{ source.label }}, {{ captured_on }}).
+- Follow the WIKI_SCHEMA. Write in the language of the page, or of the transcript for a new page.
+- If this part decided or taught nothing worth keeping, return an empty `pages` list.
+
+Answer with JSON following the schema: a list `pages`, each with `action` (create or update), `target_page_id` (the page_id you update, or null), `title`, `summary` (one sentence on what the page covers), `markdown` (the page body without frontmatter, starting with `# Title`) and `change_summary` (one short sentence for the page history); and a list `conflicts`, one per contradiction with what a page already said: `page_title`, `existing_statement` (what the page said, as written), `existing_source` (its attribution), `new_statement` and `new_source` ({{ source.label }}, {{ captured_on }}). An empty list when nothing contradicts.
+
+SOURCE:
+{{ source | json }}
+
+PART {{ part.index }} OF {{ part.total }}:
+{{ part.text }}
+
+WIKI_SCHEMA:
+{{ wiki_schema }}
+
+PAGE_INDEX:
+{{ page_index | json }}
+
+CANDIDATE_PAGES:
+{{ candidate_pages | json }}

{iatoolkit-2.66.0 → iatoolkit-2.68.0}/src/iatoolkit/config/system_agents_pack.yaml

@@ -195,6 +195,65 @@ agents:
     inputs: [source, part, captured_on, wiki_schema, page_index, candidate_pages]
     default_model: null
 
+  - key: memory_meeting_ingest
+    name: Lector de reuniones de Memoria
+    name_en: Memory meeting reader
+    description: >-
+      (Memoria de la empresa) Lee las transcripciones de reuniones de las carpetas
+      marcadas como reuniones y lleva a la wiki las decisiones, los procedimientos y
+      los responsables que se acordaron, no la conversación.
+    description_en: >-
+      (Company memory) Reads the meeting transcripts of the folders marked as
+      meetings and files into the wiki the decisions, procedures and owners agreed,
+      not the conversation.
+    module: memory
+    prompt: memory_meeting_ingest.prompt
+    output_schema:
+      type: object
+      properties:
+        pages:
+          type: array
+          items:
+            type: object
+            properties:
+              action:
+                type: string
+                enum: [create, update]
+              # Nullable as a type list: the structured-output validator rejects null under anyOf.
+              target_page_id:
+                type: [integer, "null"]
+              title:
+                type: string
+              summary:
+                type: string
+              markdown:
+                type: string
+              change_summary:
+                type: string
+            required: [action, target_page_id, title, markdown]
+            additionalProperties: false
+        conflicts:
+          type: array
+          items:
+            type: object
+            properties:
+              page_title:
+                type: string
+              existing_statement:
+                type: string
+              existing_source:
+                type: string
+              new_statement:
+                type: string
+              new_source:
+                type: string
+            required: [page_title, existing_statement, new_statement]
+            additionalProperties: false
+      required: [pages]
+      additionalProperties: false
+    inputs: [source, part, captured_on, wiki_schema, page_index, candidate_pages]
+    default_model: null
+
   - key: memory_image_ingest
     name: Lector de imágenes de Memoria
     name_en: Memory image reader

{iatoolkit-2.66.0 → iatoolkit-2.68.0}/src/iatoolkit/config/system_tools_pack.yaml

@@ -575,6 +575,64 @@ tools:
       required:
         - content
         - title
+  - function_name: iat_memory_pending_questions
+    description: Lista las preguntas sobre la empresa que la IA no supo responder y siguen abiertas, primero las que se le sugirieron a este usuario por ser quien más sabe del tema, después las más preguntadas. Úsala cuando el usuario pregunte qué preguntas tiene pendientes, quiera ayudar a completar la Memoria de la empresa o pida responder las preguntas de su área. Para responder una, usa `iat_memory_answer_question`.
+    routing_profile:
+      tags:
+        - memory
+        - company_memory
+        - questions
+        - pending
+        - unanswered
+      intents:
+        - List the unanswered questions the user could answer.
+        - Show the questions suggested to the user for their area.
+      examples:
+        - iat_memory_pending_questions(limit=5)
+      cost:
+        penalty: 0.1
+        latency_class: low
+        expensive: false
+    parameters:
+      type: object
+      properties:
+        limit:
+          type: integer
+          description: Cuántas preguntas listar, como máximo 15.
+      required: []
+  - function_name: iat_memory_answer_question
+    description: Responde una pregunta sin respuesta de la Memoria de la empresa (de `iat_memory_pending_questions`). La respuesta queda en la Memoria con el nombre del usuario, la ve TODA la empresa, y la pregunta deja de estar pendiente. Antes de llamarla, muéstrale al usuario el texto que vas a guardar y espera que lo confirme. Redacta `answer` en tono neutro, completo y autocontenido, con solo lo que el usuario dijo.
+    execution_config:
+      side_effects: true
+      destructive: false
+    routing_profile:
+      tags:
+        - memory
+        - company_memory
+        - questions
+        - answer
+        - know_how
+      intents:
+        - Answer an unanswered question of the company memory with what the user explained.
+        - Use only after the user confirms the text to save.
+      examples:
+        - iat_memory_answer_question(question_id=12, answer="El plazo de pago a proveedores es de 45 días desde la factura; para proveedores nuevos, 30.")
+      cost:
+        penalty: 0.1
+        latency_class: medium
+        expensive: false
+    parameters:
+      type: object
+      properties:
+        question_id:
+          type: integer
+          description: El id de la pregunta, de `iat_memory_pending_questions`.
+        answer:
+          type: string
+          description: La respuesta, redactada en tono neutro y autocontenida (debe entenderse sin la conversación).
+      required:
+        - question_id
+        - answer
   - 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.66.0 → iatoolkit-2.68.0}/src/iatoolkit/infra/connectors/local_file_connector.py

@@ -91,5 +91,7 @@ class LocalFileConnector(FileConnector):
             raise IAToolkitException(IAToolkitException.ErrorType.FILE_IO_ERROR,
                                      f"Error eliminando el archivo {file_path}: {e}")
 
-    def generate_presigned_url(self, file_path: str, expiration: int = 3600) -> str:
-        raise NotImplementedError("not implemented yet")
+    def generate_presigned_url(self, file_path: str, expiration: int = 3600) -> str | None:
+        # FileConnector allows None when storage has no external URL. RAG
+        # results can still return their text, and Flask streams downloads.
+        return None

{iatoolkit-2.66.0 → iatoolkit-2.68.0}/src/iatoolkit/locales/en.yaml

@@ -362,6 +362,7 @@ ui:
     profile: "Profile"
     preferences: "Preferences"
     connections: "Connections"
+    memory_questions: "Questions for me"
     first_name: "First name"
     last_name: "Last name"
     full_name: "Full name"

{iatoolkit-2.66.0 → iatoolkit-2.68.0}/src/iatoolkit/locales/es.yaml

@@ -376,6 +376,7 @@ ui:
     profile: "Perfil"
     preferences: "Preferencias"
     connections: "Conexiones"
+    memory_questions: "Preguntas para mí"
     first_name: "Nombre"
     last_name: "Apellido"
     full_name: "Nombre completo"

iatoolkit-2.68.0/src/iatoolkit/repositories/advisory_lock.py

@@ -0,0 +1,48 @@
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+"""One Postgres advisory lock helper for everything that runs once per key across workers.
+
+A Postgres advisory lock belongs to the *database connection* that took it. An
+ORM session hands its connection back to the pool on every commit, so a lock
+taken through the session can end up held by a pooled connection nobody owns,
+and released (or not) through another one. This helper always takes and
+releases the lock on its own dedicated connection, for exactly the `with` block.
+
+On SQLite (tests) there is no advisory lock: the block runs as if it held it.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+
+from sqlalchemy import text
+
+
+@contextmanager
+def advisory_lock(db_manager, namespace: int, key: int, *, wait: bool = True):
+    """
+    Holds the two-key advisory lock (namespace, key) for the block and yields
+    whether it is held: always True when `wait` (it blocks until it gets it);
+    with `wait=False`, False when someone else holds it (the block should skip).
+    """
+    if db_manager.get_dialect() not in ("postgresql", "postgres"):
+        yield True
+        return
+    params = {"namespace": int(namespace), "key": int(key)}
+    connection = db_manager.get_connection()
+    try:
+        if wait:
+            connection.execute(text("SELECT pg_advisory_lock(:namespace, :key)"), params)
+            held = True
+        else:
+            held = bool(connection.execute(text("SELECT pg_try_advisory_lock(:namespace, :key)"), params).scalar())
+        try:
+            yield held
+        finally:
+            if held:
+                connection.execute(text("SELECT pg_advisory_unlock(:namespace, :key)"), params)
+    finally:
+        connection.close()

{iatoolkit-2.66.0 → iatoolkit-2.68.0}/src/iatoolkit/repositories/knowledge_wiki_repo.py

@@ -5,15 +5,17 @@
 
 from __future__ import annotations
 
+import hashlib
 from datetime import datetime
 
 from injector import inject
-from sqlalchemy import or_
+from sqlalchemy import or_, text
 
 from iatoolkit.repositories.database_manager import DatabaseManager
 from iatoolkit.repositories.models import (
     KnowledgeWiki,
     KnowledgeWikiPage,
+    KnowledgeWikiPageIndex,
     KnowledgeWikiPageRevision,
     KnowledgeWikiPageStatus,
     KnowledgeWikiStatus,
@@ -117,6 +119,16 @@ class KnowledgeWikiRepo:
             .first()
         )
 
+    def get_pages_by_ids(self, wiki_ids: list[int], page_ids: list[int]) -> dict[int, KnowledgeWikiPage]:
+        if not wiki_ids or not page_ids:
+            return {}
+        pages = (
+            self.session.query(KnowledgeWikiPage)
+            .filter(KnowledgeWikiPage.wiki_id.in_(list(wiki_ids)), KnowledgeWikiPage.id.in_(list(page_ids)))
+            .all()
+        )
+        return {page.id: page for page in pages}
+
     def get_page_by_slug(self, wiki_id: int, slug: str) -> KnowledgeWikiPage | None:
         if not wiki_id or not slug:
             return None
@@ -203,21 +215,143 @@ class KnowledgeWikiRepo:
             )
             self.session.add(page)
         self.session.commit()
+        self.index_page(page)
         return page
 
     def save_page(self, page: KnowledgeWikiPage) -> KnowledgeWikiPage:
         self.session.add(page)
         self.session.commit()
+        self.index_page(page)
         return page
 
     def delete_page(self, wiki_id: int, path: str) -> KnowledgeWikiPage | None:
         page = self.get_page_by_path(wiki_id, path)
         if page is None:
             return None
+        self.session.query(KnowledgeWikiPageIndex).filter(KnowledgeWikiPageIndex.page_id == page.id).delete()
         self.session.delete(page)
         self.session.commit()
         return page
 
+    # =====================================================================
+    # Search index (iat_knowledge_wiki_page_index)
+    # =====================================================================
+
+    # What the word branch searches; the meaning branch embeds the same text, cut.
+    INDEX_TEXT_CHARS = 60000
+
+    @classmethod
+    def page_search_text(cls, page: KnowledgeWikiPage) -> str:
+        parts = [page.title or "", page.summary or "", " ".join(str(t) for t in (page.tags or [])), page.body_text or ""]
+        return "\n".join(part.strip() for part in parts if str(part or "").strip())[:cls.INDEX_TEXT_CHARS]
+
+    def index_page(self, page: KnowledgeWikiPage) -> KnowledgeWikiPageIndex:
+        """Writes the page's search text; a changed text clears the embedding so it is computed again."""
+        search_text = self.page_search_text(page)
+        content_hash = hashlib.sha256(search_text.encode("utf-8")).hexdigest()
+        row = self.session.query(KnowledgeWikiPageIndex).filter(KnowledgeWikiPageIndex.page_id == page.id).first()
+        if row is None:
+            row = KnowledgeWikiPageIndex(page_id=page.id, wiki_id=page.wiki_id, company_id=page.company_id)
+            self.session.add(row)
+        elif row.content_hash == content_hash and row.wiki_id == page.wiki_id:
+            return row
+        row.wiki_id = page.wiki_id
+        row.search_text = search_text
+        row.content_hash = content_hash
+        if row.embedded_hash != content_hash:
+            row.embedding = None
+            row.embedded_hash = None
+        self.session.commit()
+        return row
+
+    def list_pages_to_embed(self, limit: int = 100, company_id: int | None = None) -> list[KnowledgeWikiPageIndex]:
+        query = (
+            self.session.query(KnowledgeWikiPageIndex)
+            .join(KnowledgeWikiPage, KnowledgeWikiPage.id == KnowledgeWikiPageIndex.page_id)
+            .filter(KnowledgeWikiPage.status != KnowledgeWikiPageStatus.ARCHIVED)
+            .filter(or_(KnowledgeWikiPageIndex.embedded_hash.is_(None),
+                        KnowledgeWikiPageIndex.embedded_hash != KnowledgeWikiPageIndex.content_hash))
+        )
+        if company_id:
+            query = query.filter(KnowledgeWikiPageIndex.company_id == company_id)
+        return query.order_by(KnowledgeWikiPageIndex.updated_at.asc()).limit(limit).all()
+
+    def list_unindexed_pages(self, limit: int = 500) -> list[KnowledgeWikiPage]:
+        """Pages written before the index existed (the backfill)."""
+        return (
+            self.session.query(KnowledgeWikiPage)
+            .outerjoin(KnowledgeWikiPageIndex, KnowledgeWikiPageIndex.page_id == KnowledgeWikiPage.id)
+            .filter(KnowledgeWikiPageIndex.id.is_(None))
+            .filter(KnowledgeWikiPage.status != KnowledgeWikiPageStatus.ARCHIVED)
+            .limit(limit)
+            .all()
+        )
+
+    def set_page_embedding(self, row: KnowledgeWikiPageIndex, embedding: list[float], embedded_hash: str) -> None:
+        row.embedding = embedding
+        row.embedded_hash = embedded_hash
+        self.session.commit()
+
+    def is_postgres(self) -> bool:
+        bind = self.session.get_bind()
+        return getattr(getattr(bind, "dialect", None), "name", "") == "postgresql"
+
+    RRF_K = 60
+
+    def hybrid_search_pages(self, wiki_ids: list[int], query_text: str, query_embedding: list[float] | None,
+                            candidates: int = 40) -> list[tuple[int, float]]:
+        """
+        (page_id, rrf_score) of the best pages of these wikis, best first: by
+        words (Postgres full text, 'simple', terms OR'ed, the GIN index) and, when
+        there is a query embedding, by meaning (pages whose embedding has its
+        size), fused by Reciprocal Rank Fusion. Archived pages are left out.
+        Postgres only.
+        """
+        if not wiki_ids:
+            return []
+        tsvector = "to_tsvector('simple'::regconfig, i.search_text)"
+        tsquery = "replace(plainto_tsquery('simple'::regconfig, :text_terms)::text, ' & ', ' | ')::tsquery"
+        params = {"wiki_ids": list(wiki_ids), "text_terms": query_text or "", "candidates": int(candidates),
+                  "archived": KnowledgeWikiPageStatus.ARCHIVED.name}
+        branches = [f"""
+                SELECT page_id, ROW_NUMBER() OVER (ORDER BY text_rank DESC, page_id ASC) AS rank
+                FROM (
+                    SELECT i.page_id, ts_rank_cd({tsvector}, terms.q) AS text_rank
+                    FROM iat_knowledge_wiki_page_index i
+                    JOIN iat_knowledge_wiki_pages p ON p.id = i.page_id,
+                         (SELECT {tsquery} AS q) terms
+                    WHERE i.wiki_id = ANY(:wiki_ids) AND p.status::text <> :archived
+                      AND {tsvector} @@ terms.q
+                    ORDER BY text_rank DESC
+                    LIMIT :candidates
+                ) words"""]
+        if query_embedding:
+            dims = len(query_embedding)
+            if 0 < dims <= 2000:
+                params["query_embedding"] = str(list(query_embedding))
+                branches.append(f"""
+                SELECT page_id, ROW_NUMBER() OVER (ORDER BY distance ASC, page_id ASC) AS rank
+                FROM (
+                    SELECT i.page_id,
+                           i.embedding::vector({dims}) <=> CAST(:query_embedding AS vector({dims})) AS distance
+                    FROM iat_knowledge_wiki_page_index i
+                    JOIN iat_knowledge_wiki_pages p ON p.id = i.page_id
+                    WHERE i.wiki_id = ANY(:wiki_ids) AND p.status::text <> :archived
+                      AND i.embedding IS NOT NULL AND vector_dims(i.embedding) = {dims}
+                    ORDER BY distance ASC
+                    LIMIT :candidates
+                ) meaning""")
+        union = " UNION ALL ".join(f"({branch})" for branch in branches)
+        sql = f"""
+            SELECT page_id, SUM(1.0 / ({self.RRF_K} + rank)) AS rrf_score
+            FROM ({union}) hits
+            GROUP BY page_id
+            ORDER BY rrf_score DESC, page_id ASC
+            LIMIT :candidates
+        """
+        rows = self.session.execute(text(sql), params).fetchall()
+        return [(int(row[0]), float(row[1])) for row in rows]
+
     def create_page_revision(
         self,
         *,

{iatoolkit-2.66.0 → iatoolkit-2.68.0}/src/iatoolkit/repositories/memory_question_repo.py

@@ -51,6 +51,29 @@ class MemoryQuestionRepo:
             .all()
         )
 
+    def claim_open(self, company_id: int, question_id: int, status: str, resolved_by: str, resolved_at) -> bool:
+        """Resolves the question only if it is still open, in one UPDATE: of two people answering at
+        once, exactly one wins (Fase 0, R17). Commits."""
+        claimed = (
+            self.session.query(MemoryQuestion)
+            .filter(MemoryQuestion.company_id == company_id, MemoryQuestion.id == question_id,
+                    MemoryQuestion.status == MemoryQuestion.STATUS_OPEN)
+            .update({MemoryQuestion.status: status, MemoryQuestion.resolved_by: resolved_by,
+                     MemoryQuestion.resolved_at: resolved_at}, synchronize_session=False)
+        )
+        self.commit()
+        return bool(claimed)
+
+    def reopen(self, company_id: int, question_id: int) -> None:
+        """Undoes a claim whose answer could not be saved."""
+        (
+            self.session.query(MemoryQuestion)
+            .filter(MemoryQuestion.company_id == company_id, MemoryQuestion.id == question_id)
+            .update({MemoryQuestion.status: MemoryQuestion.STATUS_OPEN, MemoryQuestion.resolved_by: None,
+                     MemoryQuestion.resolved_at: None}, synchronize_session=False)
+        )
+        self.commit()
+
     def get_question(self, company_id: int, question_id: int) -> MemoryQuestion | None:
         return (
             self.session.query(MemoryQuestion)

{iatoolkit-2.66.0 → iatoolkit-2.68.0}/src/iatoolkit/repositories/memory_repo.py

@@ -131,6 +131,19 @@ class MemoryRepo:
             .all()
         )
 
+    def list_failed_captures(self, company_id: int, failed_before, limit: int = 50) -> list[MemoryCapture]:
+        """Captures whose compilation failed before `failed_before`, oldest first (to retry them)."""
+        if not company_id:
+            return []
+        return (
+            self.session.query(MemoryCapture)
+            .filter_by(company_id=company_id, status=MemoryCaptureStatus.FAILED)
+            .filter(MemoryCapture.updated_at < failed_before)
+            .order_by(MemoryCapture.updated_at.asc(), MemoryCapture.id.asc())
+            .limit(limit)
+            .all()
+        )
+
     def add_page_sources(self, company_id: int, wiki_page_id: int, item_ids: list[int]) -> None:
         """Links items to a wiki page, keeping the links it already has."""
         if not company_id or not wiki_page_id:

iatoolkit-2.68.0/src/iatoolkit/repositories/memory_usage_repo.py

@@ -0,0 +1,68 @@
+# Copyright (c) 2024 Fernando Libedinsky
+# Product: IAToolkit
+#
+# IAToolkit is open source software.
+
+from __future__ import annotations
+
+from collections import Counter
+from datetime import datetime
+
+from injector import inject
+from sqlalchemy import case, func
+
+from iatoolkit.common import memory_tools
+from iatoolkit.repositories.database_manager import DatabaseManager
+from iatoolkit.repositories.models import MemoryUsageEvent
+
+
+class MemoryUsageRepo:
+    """iat_memory_usage_events: one row per use of the company's knowledge (Fase 2)."""
+
+    @inject
+    def __init__(self, db_manager: DatabaseManager):
+        self.session = db_manager.get_session()
+
+    def add(self, event: MemoryUsageEvent) -> None:
+        self.session.add(event)
+        self.session.commit()
+
+    def rollback(self) -> None:
+        self.session.rollback()
+
+    def summarize(self, company_id: int, start: datetime, end: datetime) -> dict:
+        """What the company's knowledge was used for in [start, end), by tool, channel and day."""
+        base = (
+            self.session.query(MemoryUsageEvent)
+            .filter(MemoryUsageEvent.company_id == company_id,
+                    MemoryUsageEvent.created_at >= start, MemoryUsageEvent.created_at < end)
+        )
+        searches = found = 0
+        by_channel: Counter = Counter()
+        by_day: Counter = Counter()
+        found_flag = case((MemoryUsageEvent.results > 0, 1), else_=0)
+        day = func.date(MemoryUsageEvent.created_at)
+        rows = (
+            base.with_entities(MemoryUsageEvent.channel, day, found_flag, func.count(MemoryUsageEvent.id))
+            .filter(MemoryUsageEvent.tool.in_(list(memory_tools.SEARCH_TOOLS)))
+            .group_by(MemoryUsageEvent.channel, day, found_flag)
+            .all()
+        )
+        for channel, event_day, was_found, count in rows:
+            searches += count
+            if was_found:
+                found += count
+            by_channel[channel] += count
+            by_day[str(event_day)] += count
+        page_reads = Counter({str(page_id): count for page_id, count in (
+            base.with_entities(MemoryUsageEvent.page_id, func.count(MemoryUsageEvent.id))
+            .filter(MemoryUsageEvent.tool == memory_tools.PAGE_READ_TOOL, MemoryUsageEvent.page_id.isnot(None))
+            .group_by(MemoryUsageEvent.page_id).all()
+        )})
+        document_reads = Counter({str(document_id): count for document_id, count in (
+            base.with_entities(MemoryUsageEvent.document_id, func.count(MemoryUsageEvent.id))
+            .filter(MemoryUsageEvent.tool == memory_tools.DOCUMENT_READ_TOOL, MemoryUsageEvent.document_id.isnot(None))
+            .group_by(MemoryUsageEvent.document_id).all()
+        )})
+        return {"searches": searches, "searches_found": found, "by_channel": dict(by_channel),
+                "by_day": dict(by_day), "page_reads": page_reads, "document_reads": document_reads}