Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions i18n/es/docs/architecture/agno-adapter.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
<!-- i18n: source=docs/architecture/agno-adapter.md blob=3cda341b0d2ad39a80b6546d3002b103a90de53d model=claude-sonnet-5-5 -->
> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/architecture/agno-adapter.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/agno-adapter.md), which is authoritative.

<a id="agno-user-memory-database"></a>

# Base de datos de memoria de usuario de Agno

El adaptador de Agno implementa los métodos de memoria de usuario de su interfaz `BaseDb` 3.2
a través del SDK síncrono de Loom. La dependencia opcional, fijada a una versión menor, se mantiene fuera
del SDK principal y del servidor. `MemoryManager` acepta esta base de datos de forma independiente a
la base de datos de sesiones de un agente. Las capacidades que no son de memoria se rechazan en lugar de usar un almacén
predeterminado del framework.

<a id="invariants"></a>

## Invariantes

Cada adaptador se vincula a un usuario y a un almacén de aplicación. Cada llamada al SDK lleva ese usuario
y una sesión derivada; las claves incluyen el mismo digest de ámbito más un digest del id nativo.
Se rechaza un usuario explícito distinto. Las memorias de usuario nativas son JSON en filas episódicas
de Loom, que conservan ids, metadatos y revisiones sin fusión semántica de
registros nativos diferentes. La procedencia del actor y de la fuente proviene de la ruta de escritura normal de Loom.
Se aplican las reglas habituales de eliminación de memoria, borrado y esquema progresivo.

El listado sigue páginas limitadas y proyectadas, elimina duplicados por solapamiento e hidrata los valores
truncados antes de convertirlos en objetos nativos. Los filtros de contenido, temas y atribución, la ordenación, la paginación y las estadísticas se ejecutan sobre esta instantánea de usuario/almacén acotada. No hay estado persistente local. Las ediciones concurrentes conservan
la última escritura del servidor; las operaciones masivas son una secuencia de escrituras y pueden terminar
parcialmente si hay un fallo. Las concesiones de espacio de nombres aíslan aplicaciones que no confían entre sí.

<a id="source-entry-points"></a>

## Puntos de entrada del código fuente

- `sdk/python/loom/integrations/agno.py`: `LoomMemoryDb`.
- `sdk/python/tests/test_agno.py`: comportamiento nativo del gestor de memoria.
- `tests/integration/test_sdk_agno_memory.py`: ámbito de memoria y procedencia en vivo.
26 changes: 26 additions & 0 deletions i18n/es/docs/architecture/google-adk-adapter.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<!-- i18n: source=docs/architecture/google-adk-adapter.md blob=6c709e61102ee7413e9b4764bfd5c80f4511830e model=claude-sonnet-5-5 -->
> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/architecture/google-adk-adapter.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/google-adk-adapter.md), which is authoritative.

<a id="google-adk-memory-service"></a>

# Servicio de memoria de Google ADK

El adaptador de Google ADK implementa el servicio de memoria del framework a través de los SDK de Python y TypeScript de Loom. Los paquetes del framework son dependencias opcionales. Cada aplicación usa un espacio de nombres de Loom distinto, porque sus documentos de conocimiento se comparten con todos los lectores de ese espacio de nombres.

Las escrituras de sesión extraen texto de los eventos activos del usuario y del modelo, excluyendo las cargas de herramientas y los pensamientos, y luego llaman a `memory.set_from_messages` en lotes acotados. Ambos SDK rechazan ids de usuario vacíos, centinela o con espacios en los extremos antes de realizar cualquier llamada. Cada llamada incluye al usuario final y una sesión derivada del usuario y del id de sesión nativo. Python también implementa los métodos de eventos incrementales, memoria directa y eliminación del framework instalado. Los ids de eliminación de Python incluyen la clave, la sesión, el escritor y la versión exacta. Llaman directamente a `memory.delete_version`. Una versión inexistente o reescrita no produce ningún efecto, y nunca se selecciona la fila de otro escritor. El campo de respuesta adicional `agent` en los resultados de búsqueda de memoria proviene de la identidad de la fila almacenada, incluidas las páginas aparcadas. Un resultado sin escritor o versión conocidos no tiene id de eliminación. Los clientes antiguos ignoran el campo adicional; la eliminación exacta en ADK requiere un servidor que lo proporcione. Esto no añade ninguna columna persistida ni migración. TypeScript devuelve ids informativos acotados al escritor; la interfaz del framework instalada no tiene un método de eliminación.

La búsqueda primero llama a `memory.search` para el usuario vinculado y después rellena los espacios de resultados disponibles con `knowledge.search`, acotada al espacio de nombres. El conocimiento es contexto compartido de la aplicación, no memoria privada del usuario. Los dos SDK usan la misma codificación de digest; la representación nativa de marcas de tiempo del framework se convierte en el límite. Una instancia del servicio está vinculada a una aplicación. Los permisos por espacio de nombres aíslan aplicaciones que no confían entre sí.

<a id="source-entry-points"></a>

## Puntos de entrada del código fuente

- `sdk/python/loom/integrations/google_adk.py`: `LoomMemoryService`.
- `sdk/typescript/src/integrations/google-adk.ts`: `LoomMemoryService`.

<a id="invariants"></a>

## Invariantes

El servidor proporciona la procedencia del actor y de la fuente a través de su ruta de escritura habitual. El adaptador no añade ninguna base de datos, esquema ni proveedor. Se aplican las reglas existentes de eliminación de memoria, borrado de conocimiento y actualización progresiva. La extracción semántica puede revisar hechos; este servicio no es un almacén exacto de transcripciones. Los resultados de conocimiento no tienen id de memoria de usuario y no pueden eliminarse a través del servicio de memoria.
27 changes: 27 additions & 0 deletions i18n/es/docs/architecture/haystack-adapter.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<!-- i18n: source=docs/architecture/haystack-adapter.md blob=c2cfa8a3d7cfb7c046a16c39b584aa93d1ea0420 model=claude-sonnet-5-5 -->
> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/architecture/haystack-adapter.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/haystack-adapter.md), which is authoritative.

<a id="haystack-document-store-and-retriever"></a>

# Document store y retriever de Haystack

El adaptador opcional de Haystack 3.5 implementa su protocolo de document store y un componente de recuperación nativo a través del SDK síncrono de Loom. El SDK principal y el servidor no dependen del framework. Cada llamada HTTP tiene un ciclo de vida de cliente gestionado por el SDK; el adaptador no deja ningún servidor, base de datos local, caché ni proceso persistente en segundo plano.

<a id="invariants"></a>

## Invariantes

Un store asigna cada id de documento nativo a un URI de origen con hash bajo un prefijo específico del store. Una etiqueta coincidente delimita el listado y la recuperación. La serialización nativa completa del documento, incluidos los metadatos, los embeddings y los campos binarios, se guarda en los bytes del archivo original del documento. Los metadatos del fragmento llevan únicamente un pequeño marcador de formato; el texto se indexa como contenido del documento, o el id cuando no hay texto. Las rutas normales de Loom para escritura de documentos, procedencia, permisos del espacio de nombres, versionado y borrado se aplican a cada escritura y eliminación. Los documentos se comparten en el espacio de nombres y no son privados de un usuario.

El conteo y el filtrado cargan todo el store mediante páginas de cursor. Los helpers de filtro nativos aplican comparaciones y lógica booleana. La recuperación busca hasta 100 fragmentos con límites explícitos de espacio de nombres, etiqueta y URI, carga los documentos completos y elimina duplicados por URI de origen, conservando el resultado mejor clasificado de cada documento. Estas operaciones no tienen una instantánea entre solicitudes. Las escrituras concurrentes pueden provocar un conflicto devuelto por Loom. Las comprobaciones de duplicados y las operaciones sobre varios documentos no son transacciones.

Las conexiones serializadas llevan referencias Secret de variables de entorno de Haystack; los tokens Secret sin procesar rechazan la serialización. Las URL de endpoint explícitas rechazan secretos incrustados. El adaptador conserva la política de confianza de deserialización de pipelines de Haystack y nunca registra módulos de confianza ni selecciona la deserialización insegura.

<a id="source-entry-points"></a>

## Puntos de entrada del código fuente

- `sdk/python/loom/integrations/haystack.py`: `LoomDocumentStore` y `LoomRetriever`.
- `sdk/python/tests/test_haystack.py`: comportamiento nativo del document store y del pipeline.
- `tests/integration/test_sdk_haystack.py`: persistencia y recuperación de documentos en vivo.
Loading
Loading