diff --git a/i18n/es/docs/architecture/agno-adapter.md b/i18n/es/docs/architecture/agno-adapter.md new file mode 100644 index 0000000000..2edb3427a1 --- /dev/null +++ b/i18n/es/docs/architecture/agno-adapter.md @@ -0,0 +1,37 @@ + +> 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. + + + +# 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. + + + +## 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í. + + + +## 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. diff --git a/i18n/es/docs/architecture/google-adk-adapter.md b/i18n/es/docs/architecture/google-adk-adapter.md new file mode 100644 index 0000000000..8f8114ef9b --- /dev/null +++ b/i18n/es/docs/architecture/google-adk-adapter.md @@ -0,0 +1,26 @@ + +> 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. + + + +# 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í. + + + +## Puntos de entrada del código fuente + +- `sdk/python/loom/integrations/google_adk.py`: `LoomMemoryService`. +- `sdk/typescript/src/integrations/google-adk.ts`: `LoomMemoryService`. + + + +## 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. diff --git a/i18n/es/docs/architecture/haystack-adapter.md b/i18n/es/docs/architecture/haystack-adapter.md new file mode 100644 index 0000000000..8c6f63cde0 --- /dev/null +++ b/i18n/es/docs/architecture/haystack-adapter.md @@ -0,0 +1,27 @@ + +> 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. + + + +# 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. + + + +## 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. + + + +## 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. diff --git a/i18n/es/docs/reference/operations/working_memory.md b/i18n/es/docs/reference/operations/working_memory.md new file mode 100644 index 0000000000..6c86f83f5f --- /dev/null +++ b/i18n/es/docs/reference/operations/working_memory.md @@ -0,0 +1,179 @@ + +> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/working_memory.md), que prevalece. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/working_memory.md), which is authoritative. + + + +# Operaciones de `working_memory` + +Los campos exactos que recibe y devuelve cada operación `working_memory.*`. + + + +Cada op es `POST /v1/` sobre HTTP y la herramienta MCP `loom_`. Los campos de identidad (`org`, `namespace`, `agent`, `user_id`, `session_id`) se rellenan a partir del token y de la sesión MCP cuando el transporte puede hacerlo; en una llamada HTTP sin token a un servidor de un solo usuario, se rellena la org de la instalación en todas las ops excepto `code.*` y `tracker.*` (que conservan la de su plano), y en [algunas ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request) también su espacio de nombres y su agente; consulta [identidades y espacios de nombres](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md). El [índice de operaciones](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica el rol, el tipo y el listado `all` de MCP. Los campos de entrada desconocidos se atienden y se nombran en `ignored_args`. + + + + + +## `working_memory.append` + +Agrega texto a un bloque de memoria de trabajo y lo crea si no existe. + +`POST /v1/working_memory.append` · MCP `loom_working_memory_append` · rol `writer` · escritura + +| Campo de entrada | Tipo | Valor por defecto | Significado | +| --- | --- | --- | --- | +| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). | +| `namespace` | `str` | obligatorio | El espacio de nombres que la operación lee o escribe. | +| `agent` | `str` | obligatorio | El agente que escribe o lee; `'-'` o `'*'` significa cualquier agente cuando la operación lo permite. | +| `user_id` | `str` | `'-'` | El usuario final al que pertenece la fila; `'-'` si no hay ninguno. | +| `session_id` | `str` | `'-'` | La sesión o conversación a la que pertenece la fila; `'-'` si no hay ninguna. | +| `run_id` | `str` | `'-'` | La ejecución del agente (ámbito de tarea) a la que pertenece la llamada; `'-'` si no hay ninguna. | +| `block_key` | `str` | `'scratchpad'` | El bloque al que se agrega; un bloque inexistente se crea con el límite de tamaño por defecto. | +| `addition` | `str` | obligatorio | Texto que se agrega al final del bloque. | +| `separator` | `str` | `'\n'` | Se coloca entre el texto existente y `addition`; no se usa cuando el bloque es nuevo. | + +| Campo de salida | Tipo | Significado | +| --- | --- | --- | +| `block_key` | `str` | El bloque que se escribió. | +| `version` | `int` | Versión de la fila que creó esta escritura (una marca de tiempo en nanosegundos). | +| `char_limit` | `int` | El límite de tamaño del bloque en caracteres después de la escritura. | +| `value_length` | `int` | Longitud del contenido del bloque después de la escritura, en caracteres. | +| `fill_ratio` | `float` | `value_length / char_limit`, con tres decimales; se rechaza una escritura que superaría 1.0. | + + + +## `working_memory.delete` + +Elimina un bloque de memoria de trabajo. + +`POST /v1/working_memory.delete` · MCP `loom_working_memory_delete` · rol `writer` · idempotente · no figura en el toolset `all` de MCP + +| Campo de entrada | Tipo | Valor por defecto | Significado | +| --- | --- | --- | --- | +| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). | +| `namespace` | `str` | obligatorio | El espacio de nombres que la op lee o escribe. | +| `agent` | `str` | obligatorio | El agente que escribe o lee; `'-'` o `'*'` significa cualquier agente cuando la op lo permite. | +| `user_id` | `str` | `'-'` | El usuario final al que pertenece la fila; `'-'` si no hay ninguno. | +| `session_id` | `str` | `'-'` | La sesión o conversación a la que pertenece la fila; `'-'` si no hay ninguna. | +| `run_id` | `str` | `'-'` | La ejecución del agente (ámbito de tarea) a la que pertenece la llamada; `'-'` si no hay ninguna. | +| `block_key` | `str` | `'scratchpad'` | El bloque que se va a eliminar. | + +| Campo de salida | Tipo | Significado | +| --- | --- | --- | +| `deleted` | `bool` | False cuando el ámbito no contenía ningún bloque activo con esta clave. | +| `block_key` | `str` | Eco del `block_key` de entrada. | + + + +## `working_memory.get` + +Obtiene un bloque de memoria de trabajo por su clave. + +`POST /v1/working_memory.get` · MCP `loom_working_memory_get` · rol `viewer` · lectura · no aparece en el conjunto de herramientas `all` de MCP + +| Campo de entrada | Tipo | Valor por defecto | Significado | +| --- | --- | --- | --- | +| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). | +| `namespace` | `str` | obligatorio | El espacio de nombres que la op lee o escribe. | +| `agent` | `str` | obligatorio | El agente que escribe o lee; `'-'` o `'*'` significa cualquier agente donde la op lo permita. | +| `user_id` | `str` | `'-'` | El usuario final al que pertenece la fila; `'-'` si no hay ninguno. | +| `session_id` | `str` | `'-'` | La sesión o conversación a la que pertenece la fila; `'-'` si no hay ninguna. | +| `run_id` | `str` | `'-'` | La ejecución del agente (ámbito de tarea) a la que pertenece la llamada; `'-'` si no hay ninguna. | +| `block_key` | `str` | `'scratchpad'` | El bloque que se lee, dentro del ámbito (agent, user, session, run) del llamador. | + +| Campo de salida | Tipo | Significado | +| --- | --- | --- | +| `found` | `bool` | False cuando el ámbito no contiene ningún bloque vigente con esta clave; el resto toma entonces los valores por defecto. | +| `block_key` | `str` | Eco de la clave del bloque. | +| `content` | `str` | El texto del bloque; vacío si no se encuentra. | +| `char_limit` | `int` | El límite de tamaño del bloque en caracteres; una escritura que lo supere se rechaza con 422. | +| `version` | `int` | Versión de la fila actual del bloque (una marca de tiempo en nanosegundos); 0 si no se encuentra. | +| `updated_at` | `datetime \| None` | Cuándo se escribió el bloque por última vez; None si no se encuentra. | +| `fill_ratio` | `float` | len(content) / char_limit. | + + + +## `working_memory.render` + +Renderiza bloques de memoria de trabajo como XML o markdown. context.pack ya incluye esta sección; el renderizado directo se usa sobre todo en código de SDK o de orquestación personalizada. + +`POST /v1/working_memory.render` · MCP `loom_working_memory_render` · rol `viewer` · lectura + +| Campo de entrada | Tipo | Valor por defecto | Significado | +| --- | --- | --- | --- | +| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). | +| `namespace` | `str` | obligatorio | El espacio de nombres que la operación lee o escribe. | +| `agent` | `str` | obligatorio | El agente que escribe o lee; `'-'` o `'*'` significa cualquier agente donde la operación lo permita. | +| `user_id` | `str` | `'-'` | El usuario final al que pertenece la fila; `'-'` para ninguno. | +| `session_id` | `str` | `'-'` | La sesión o conversación a la que pertenece la fila; `'-'` para ninguna. | +| `run_id` | `str` | `'-'` | La ejecución del agente (ámbito de tarea) a la que pertenece la llamada; `'-'` para ninguna. | +| `block_keys` | `list[str]` | *(calculado)* | Solo estos bloques (como máximo 20); vacío = todos los bloques vigentes en el ámbito. | +| `format` | `Literal['xml', 'markdown']` | `'xml'` | `xml` envuelve cada bloque en una etiqueta ``; `markdown` lo coloca bajo un encabezado `## `. | +| `limit` | `int` | `20` | Como máximo este número de bloques, en orden de `block_key` (1-100). | + +| Campo de salida | Tipo | Significado | +| --- | --- | --- | +| `rendered` | `str` | Los bloques como un único texto en el `format` elegido; vacío cuando el ámbito no tiene ninguno. | +| `blocks` | `list[WorkingMemoryBlock]` | Los bloques renderizados con sus límites de tamaño y versiones, en orden de `block_key`. | +| `block_count` | `int` | Cuántos bloques se renderizaron. | +| `total_chars` | `int` | Suma de las longitudes del contenido de los bloques, en caracteres. | + + + +## `working_memory.replace` + +Reemplaza texto exacto dentro de un bloque de memoria de trabajo. + +`POST /v1/working_memory.replace` · MCP `loom_working_memory_replace` · rol `writer` · idempotente · no figura en el conjunto de herramientas MCP `all` + +| Campo de entrada | Tipo | Valor por defecto | Significado | +| --- | --- | --- | --- | +| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). | +| `namespace` | `str` | obligatorio | El espacio de nombres que la op lee o escribe. | +| `agent` | `str` | obligatorio | El agente que escribe o lee; `'-'` o `'*'` significa cualquier agente donde la op lo permita. | +| `user_id` | `str` | `'-'` | El usuario final al que pertenece la fila; `'-'` si ninguno. | +| `session_id` | `str` | `'-'` | La sesión o conversación a la que pertenece la fila; `'-'` si ninguna. | +| `run_id` | `str` | `'-'` | La ejecución del agente (ámbito de tarea) a la que pertenece la llamada; `'-'` si ninguna. | +| `block_key` | `str` | `'scratchpad'` | El bloque que se edita; un bloque inexistente devuelve un 404. | +| `old` | `str` | obligatorio | Texto a buscar; se reemplaza cada aparición, y si el texto no existe se devuelve un 422. | +| `new` | `str` | `''` | Texto de reemplazo; si está vacío, elimina las apariciones de `old`. | + +| Campo de salida | Tipo | Significado | +| --- | --- | --- | +| `block_key` | `str` | El bloque que se escribió. | +| `version` | `int` | Versión de la fila que creó esta escritura (una marca de tiempo en nanosegundos). | +| `char_limit` | `int` | El límite de tamaño del bloque en caracteres tras la escritura. | +| `value_length` | `int` | Longitud del contenido del bloque tras la escritura, en caracteres. | +| `fill_ratio` | `float` | `value_length / char_limit`, con tres decimales; se rechaza una escritura que superaría 1.0. | + + + +## `working_memory.set` + +Sobrescribe un bloque de memoria de trabajo. + +`POST /v1/working_memory.set` · MCP `loom_working_memory_set` · rol `writer` · idempotente + +| Campo de entrada | Tipo | Valor por defecto | Significado | +| --- | --- | --- | --- | +| `org` | `str` | obligatorio | El tenant (primer elemento de la tupla de identidad). | +| `namespace` | `str` | obligatorio | El espacio de nombres que la op lee o escribe. | +| `agent` | `str` | obligatorio | El agente que escribe o lee; `'-'` o `'*'` significa cualquier agente donde la op lo permita. | +| `user_id` | `str` | `'-'` | El usuario final al que pertenece la fila; `'-'` si no hay ninguno. | +| `session_id` | `str` | `'-'` | La sesión o conversación a la que pertenece la fila; `'-'` si no hay ninguna. | +| `run_id` | `str` | `'-'` | La ejecución del agente (ámbito de la tarea) a la que pertenece la llamada; `'-'` si no hay ninguna. | +| `block_key` | `str` | `'scratchpad'` | El bloque que se escribe, dentro del ámbito (agente, usuario, sesión, ejecución) de quien llama. | +| `content` | `str` | `''` | El texto nuevo completo del bloque, que reemplaza lo que contenía; si está vacío, se guarda un bloque vacío. | +| `char_limit` | `int` | `4096` | El límite de tamaño del bloque en caracteres; un `content` más largo se rechaza con 422. | + +| Campo de salida | Tipo | Significado | +| --- | --- | --- | +| `block_key` | `str` | El bloque que se escribió. | +| `version` | `int` | Versión de la fila que creó esta escritura (una marca de tiempo en nanosegundos). | +| `char_limit` | `int` | El límite de tamaño del bloque en caracteres después de la escritura. | +| `value_length` | `int` | Longitud del contenido del bloque después de la escritura, en caracteres. | +| `fill_ratio` | `float` | `value_length / char_limit`, con tres decimales; una escritura que superaría 1.0 se rechaza. | + + diff --git a/i18n/ja/docs/architecture/agno-adapter.md b/i18n/ja/docs/architecture/agno-adapter.md new file mode 100644 index 0000000000..14797b68ea --- /dev/null +++ b/i18n/ja/docs/architecture/agno-adapter.md @@ -0,0 +1,25 @@ + +> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/agno-adapter.md)の機械翻訳です。内容は英語の原文が優先されます。 +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/agno-adapter.md), which is authoritative. + + + +# Agno ユーザーメモリデータベース + +Agno アダプターは、同期版 Loom SDK を通じて、3.2 の `BaseDb` インターフェースにおけるユーザーメモリのメソッドを実装します。マイナーバージョンを固定したオプションの依存関係は、コア SDK とサーバーには含まれません。`MemoryManager` は、エージェントのセッションデータベースとは独立して、このデータベースを受け付けます。メモリ以外の機能については、フレームワーク既定のストアを使わずに拒否します。 + + + +## 不変条件 + +各アダプターは、ユーザーとアプリケーションストアに紐づきます。すべての SDK 呼び出しには、そのユーザーと、そこから導出したセッションが付与されます。キーには、同じスコープダイジェストとネイティブ ID のダイジェストが含まれます。明示的に指定された別のユーザーは拒否されます。ネイティブのユーザーメモリは、Loom のエピソード行に JSON として保存され、異なるネイティブレコードをセマンティックにマージすることなく、ID、メタデータ、リビジョンが保持されます。アクターとソースの来歴は、Loom の通常の書き込みパスから取得されます。通常のメモリ削除、消去、ローリングスキーマのルールが適用されます。 + +一覧取得は、件数を制限し項目を絞り込んだページに沿って行われ、重複する部分を取り除き、切り詰められた値を補完してからネイティブオブジェクトに変換します。内容、トピック、帰属のフィルター、並べ替え、ページネーション、統計は、このユーザーとストアにスコープされたスナップショット上で実行されます。ローカルの永続状態はありません。同時編集では、サーバーへの最後の書き込みが採用されます。一括操作は書き込みの連続であり、失敗時には一部だけが完了することがあります。相互に信頼できないアプリケーションは、名前空間のグラントで分離します。 + + + +## ソースのエントリポイント + +- `sdk/python/loom/integrations/agno.py`: `LoomMemoryDb`。 +- `sdk/python/tests/test_agno.py`: ネイティブのメモリマネージャーの動作。 +- `tests/integration/test_sdk_agno_memory.py`: 実環境でのメモリのスコープと来歴。 diff --git a/i18n/ja/docs/architecture/google-adk-adapter.md b/i18n/ja/docs/architecture/google-adk-adapter.md new file mode 100644 index 0000000000..a6d70741bc --- /dev/null +++ b/i18n/ja/docs/architecture/google-adk-adapter.md @@ -0,0 +1,26 @@ + +> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/google-adk-adapter.md)の機械翻訳です。内容は英語の原文が優先されます。 +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/google-adk-adapter.md), which is authoritative. + + + +# Google ADK メモリサービス + +Google ADK アダプターは、Loom の Python SDK と TypeScript SDK を通じて、フレームワークのメモリサービスを実装します。フレームワークのパッケージはオプションの依存関係です。ナレッジドキュメントは、その名前空間のすべての読み取り側と共有されるため、各アプリケーションは個別の Loom 名前空間を使用します。 + +セッションの書き込みでは、有効なユーザーイベントとモデルイベントからテキストを抽出し(ツールのペイロードと thoughts は除外)、上限付きのバッチで `memory.set_from_messages` を呼び出します。どちらの SDK も、空のユーザー ID、センチネル値のユーザー ID、前後に空白が付いたユーザー ID を、呼び出しの前に拒否します。各呼び出しには、エンドユーザーと、そのユーザーおよびネイティブのセッション ID から導出したセッションが含まれます。Python は、インストールされているフレームワークの増分イベント、直接メモリ、削除の各メソッドも実装します。Python の削除 ID には、キー、セッション、ライター、正確なバージョンが含まれます。削除 ID は `memory.delete_version` を直接呼び出します。存在しないバージョンや書き換えられたバージョンは何も行わず、他のライターの行が選択されることはありません。メモリ検索ヒットに追加された `agent` レスポンスフィールドは、パークされたページも含め、保存された行の ID に由来します。ライターまたはバージョンが不明なヒットには、削除 ID がありません。古いクライアントは追加フィールドを無視しますが、ADK での正確な削除には、このフィールドを提供するサーバーが必要です。この変更で、永続化される列やマイグレーションは追加されません。TypeScript はライター単位の参照用 ID を返します。インストールされているフレームワークのインターフェースには、削除メソッドがありません。 + +検索では、まずバインドされたユーザーに対して `memory.search` を呼び出し、その後、空いている結果枠を名前空間単位の `knowledge.search` の結果で埋めます。ナレッジは共有されるアプリケーションコンテキストであり、ユーザー個人のメモリではありません。2 つの SDK は同じダイジェストエンコーディングを使用し、フレームワーク固有のタイムスタンプ表現は境界で変換されます。1 つのサービスインスタンスは 1 つのアプリケーションにバインドされます。相互に信頼できないアプリケーション同士は、名前空間の権限付与によって分離します。 + + + +## ソースのエントリーポイント + +- `sdk/python/loom/integrations/google_adk.py`: `LoomMemoryService`。 +- `sdk/typescript/src/integrations/google-adk.ts`: `LoomMemoryService`。 + + + +## 不変条件 + +アクターとソースの来歴は、サーバーが通常の書き込みパスを通じて提供します。アダプターは、データベース、スキーマ、プロバイダーを追加しません。既存のメモリ削除、ナレッジ消去、ローリングアップグレードのルールが適用されます。セマンティック抽出によってファクトが修正されることがあるため、このサービスは正確なトランスクリプトストアではありません。ナレッジの結果にはユーザーメモリ ID がなく、メモリサービスを通じて削除することはできません。 diff --git a/i18n/ja/docs/architecture/haystack-adapter.md b/i18n/ja/docs/architecture/haystack-adapter.md new file mode 100644 index 0000000000..1484c5efae --- /dev/null +++ b/i18n/ja/docs/architecture/haystack-adapter.md @@ -0,0 +1,27 @@ + +> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/haystack-adapter.md)の機械翻訳です。内容は英語の原文が優先されます。 +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/haystack-adapter.md), which is authoritative. + + + +# Haystack ドキュメントストアとリトリーバー + +オプションの Haystack 3.5 アダプターは、同期版 Loom SDK を通じて、ドキュメントストアのプロトコルとネイティブのリトリーバルコンポーネントを実装します。コア SDK とサーバーはこのフレームワークに依存しません。各 HTTP 呼び出しのクライアントの有効期間は SDK が管理します。アダプターは、サーバー、ローカルデータベース、キャッシュ、永続的なバックグラウンドプロセスを残しません。 + + + +## 不変条件 + +ストアは、各ネイティブドキュメント ID を、ストア固有のプレフィックスの下にあるハッシュ化されたソース URI に対応付けます。一致するタグによって、一覧取得と検索の範囲が決まります。メタデータ、埋め込み、バイナリフィールドを含むネイティブドキュメントの完全なシリアライズ結果は、ドキュメントの元ファイルのバイト列に格納されます。チャンクのメタデータには小さなフォーマットマーカーだけを持たせます。テキストはドキュメントのコンテンツとしてインデックスされ、テキストがない場合は ID がインデックスされます。すべての書き込みと削除には、Loom の通常のドキュメント書き込み、来歴、名前空間グラント、バージョン管理、消去の各経路が適用されます。ドキュメントは、ユーザー専用ではなく名前空間で共有されます。 + +件数の取得とフィルタリングでは、カーソルページを通じてストア全体をハイドレートします。ネイティブのフィルタヘルパーが、比較とブール論理を適用します。検索では、名前空間、タグ、URI の境界を明示して最大 100 チャンクを検索し、完全なドキュメントをハイドレートします。その後、ソース URI で重複を除去し、各ドキュメントで最も上位にランクされたヒットを保持します。これらの操作には、リクエストをまたぐスナップショットはありません。同時に書き込みが行われると、Loom からコンフリクトが返されることがあります。重複チェックと複数ドキュメントにまたがる操作は、トランザクションではありません。 + +シリアライズされた接続には、Haystack の環境変数 Secret 参照が含まれます。生の Secret トークンはシリアライズを拒否されます。明示的なエンドポイント URL に、シークレットを埋め込むことはできません。アダプターは Haystack のパイプラインのデシリアライズに関する信頼ポリシーを維持し、信頼するモジュールを登録することも、安全でないデシリアライズを選択することもありません。 + + + +## ソースのエントリーポイント + +- `sdk/python/loom/integrations/haystack.py`: `LoomDocumentStore` と `LoomRetriever`。 +- `sdk/python/tests/test_haystack.py`: ネイティブのドキュメントストアとパイプラインの動作。 +- `tests/integration/test_sdk_haystack.py`: 実環境でのドキュメントの永続化と検索。 diff --git a/i18n/ja/docs/features/tracker/record-contract.md b/i18n/ja/docs/features/tracker/record-contract.md new file mode 100644 index 0000000000..e42e739dc9 --- /dev/null +++ b/i18n/ja/docs/features/tracker/record-contract.md @@ -0,0 +1,286 @@ + +> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/record-contract.md)の機械翻訳です。内容は英語の原文が優先されます。 +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/record-contract.md), which is authoritative. + + + +# トラッカーレコードコントラクト + +`tracker.*` op、および `code.*` と `loom_search` のトラッカー部分は、チーム自身の ClickHouse から、読み取り専用の認証情報を使って、チームの issue、プルリクエスト、インシデントをライブで読み取ります。Loom はレコードをコピーしません。すべてのステートメントは、下記のテーブルとカラムからなる 1 つの論理モデル、つまり**コントラクト**に対して記述されます。 + +チームは、次の 2 つの方法のいずれかでスキーマを接続します。 + +| モード | 方法 | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| ビュー | チームがコントラクトのテーブル名とカラム名を持つビューを作成します。Loom はそれらをそのまま読み取ります。 | +| マッピング | Loom は認証情報で読み取れるテーブルを一覧表示し、マッピングを提案します。確定したマッピングはデータとして保存され、リモート側では何も作成されません。 | + +マッピングはコントラクトの手前にある射影にすぎないため、どのソースに対しても同じステートメント、テスト、プライバシー述語が実行されます。コード上のコントラクトは `server/tracker/domain/contract.py`(`REQUIRED`、`OPTIONAL`、`FEATURES`、`ALIASES`)、マッピングは `server/tracker/domain/mapping.py`、テーブルごとに読み取るカラムは `server/tracker/domain/columns.py` の `COLUMNS_READ` です。 + + + +## トラッカーソースの追加 + +1. **`readonly = 2` で、Loom 用の読み取り専用 ClickHouse ユーザーを作成します。** `readonly = 1` では、Loom がすべての読み取りに付与するクエリ単位の設定が拒否されるため、どの読み取りも実行されません(`CREDENTIAL_READONLY_MODE`)。 + + ```sql + CREATE USER loom_ro IDENTIFIED BY '…' SETTINGS readonly = 2; + GRANT SELECT ON system.columns TO loom_ro; + -- views mode: the views only + GRANT SELECT ON loom_tracker.* TO loom_ro; + -- mapping mode instead: each mapped table + GRANT SELECT ON tracker_db.tickets TO loom_ro; + ``` + +2. **views モードのみ:ビューを作成します。** データベース(例:`loom_tracker`)に `github_issues`、`github_prs`、`edges` を作成し、データがあるオプションのテーブルも追加します。ビューは `DEFINER = CURRENT_USER SQL SECURITY DEFINER` で作成してください。これにより、`loom_ro` に必要なのはビューへの `SELECT` だけで、背後のテーブルへの権限は不要です。通常のビューは読み取り側自身の権限で読み取るため、すべての読み取りが `ACCESS_DENIED` で失敗します。登録時のチェックがこれを検出し、修正方法を示します。ClickHouse 以外のソースは、`PostgreSQL`、`MySQL`、`S3` エンジンのテーブルの背後に置けます。`tracker.contract` は、すべてのテーブルとカラムについて保持する内容と、テーブルごとの空のビューテンプレートを返します。これには、項目の `id` 用の `loom_uuid5(name)` SQL 関数も含まれます。 + +3. **ソースを登録します。** 組織にサインインしているメンバーであれば誰でも、ダッシュボードの _Add a tracker_ フロー([トラッカーの概要](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/overview.md#adding-a-tracker-from-the-dashboard))または以下の op で登録できます。登録者は、そのトラッカーの名前空間の最初の `admin` になります。何かを書き込む前に、Loom は次の点を確認します。ホストが公開アドレスに解決されること(`HOST_REFUSED`)、認証情報が読み取り専用であること(`CREDENTIAL_NOT_READONLY`、`CREDENTIAL_READONLY_MODE`)、接続できること(`SOURCE_UNREACHABLE`)、スキーマまたはマッピングがコントラクトを満たすこと(`CONTRACT_FAILED`)です。読み取り専用とは、`SHOW GRANTS` と `SHOW GRANTS FINAL` が列挙するすべてのアクセス種別(付与されたロールの種別を含む)が、`SELECT`、データベース・テーブル・カラム・ディクショナリの `SHOW`、`dictGet`、`CREATE TEMPORARY TABLE` のいずれかであり、`WITH GRANT OPTION` や `WITH ADMIN OPTION` で付与されたものが(ネストされたロールも含め)ないことを意味します。それ以外の種別は拒否されます。ユーザーに付与されたロールはすべてデフォルトロールである必要があり、これによりチェックがロールの連鎖全体を確認できます。`SHOW GRANTS FINAL` を受け付けないサーバーは拒否されます(`SOURCE_UNREACHABLE`)。`dry_run: true` を指定すると、スキーマが不合格の場合は代わりにレポートが返され、不合格のテーブルごとに `CREATE OR REPLACE VIEW` の草案が付きます。 + + | Op | 内容 | + | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `tracker.contract` | 接続の前に、コントラクトとビューテンプレートを返します。 | + | `tracker.source.inspect` | 接続して、読み取り可能なすべてのテーブルをカラムとともに一覧し、マッピング案も示します。何も書き込みません。 | + | `tracker.source.add` | `name`、`host`、`port`(8443)、`secure`(true)、`database`、`user`、`password`、`namespaces`、オプションの `mapping`。`dry_run: true` はすべてのチェックを実行し、何も書き込みません。 | + | `tracker.source.set_mapping` | 登録済みソースのマッピングを置き換えます(`dry_run` も可)。`mapping: null` で views モードに戻します。 | + | `tracker.source.check` | コントラクトチェックを今すぐ再実行します。 | + | `tracker.source.rotate` | 認証情報を置き換えます。 | + | `tracker.source.remove` | ソースとその名前空間を廃止します(`confirm`)。 | + | `tracker.source.list` | 組織のすべてのソースについて、コントラクトの判定、ブレーカーの状態、名前空間、各名前空間での呼び出し元の立場を返します。認証情報は一切返されません。 | + + `namespaces` の各要素は `{namespace, repos, restricted, join_policy}` です。`repos` は、その名前空間が読み取れる `source_id` の `Org/repo` プレフィックスです(一覧にないリポジトリは読み取られません)。`restricted` は、その名前空間を非公開の記録にします。`join_policy` は `open`(デフォルト)で、標準の名前空間では `approval` も指定できます。セルフサービス登録には `LOOM_TRACKER_ORG` が必要で、デフォルトで有効です(`LOOM_TRACKER_SELF_SERVICE_ENABLED`。組織あたり最大 `LOOM_TRACKER_SELF_SERVICE_MAX_SOURCES` 件、デフォルトは 10。ローカル開発用の ClickHouse には `LOOM_TRACKER_SELF_SERVICE_ALLOW_PRIVATE_HOSTS=true`)。パスワードは暗号化して保存され、返されることはありません。名前での `inspect` には、そのソースのいずれかの名前空間に対する `admin` が必要です。`set_mapping`、`rotate`、`remove` は、ソースのすべての名前空間の読み取り内容を変えるため、それをすべての名前空間に対して持っている必要があります。標準の名前空間は `admin` でのゲートにより判定され、制限付きの名前空間は、トークンがその名前空間を指定する必要がない点を除き、制限付きゲートのルールにより判定されます。登録者の権限が取り消された後は、ソースを登録しただけでは足りません([制限付き名前空間](https://github.com/ClickHouse/loom/blob/main/docs/architecture/security.md#restricted-namespaces))。プラットフォーム管理者以外のダッシュボードセッションは `writer` トークンであるため、非公開(制限付き)の名前空間を持つソースを変更または廃止できません。それには `admin` ロールのトークンが必要で、オペレーターが `loom mint-token --roles admin` で発行します。ページにはこれらのボタンが理由付きで無効表示されますが、判断するのはサーバーです。 + + オペレーターは、代わりに同じソースを設定ファイルで構成することもできます([設定](#configuration))。設定されたエントリは、同名の登録済みエントリより優先され、変更は設定でのみ行えます(`SOURCE_FROM_CONFIG`)。 + +4. **Loom が名前空間のディレクトリ行を作成します。** `kind = tracker`、非公開で、制限付きの名前空間は `classification = restricted` です。`join_policy` は、標準の名前空間では `open`(または `approval`)、制限付きの名前空間では `approval` になります。 + +5. **読み取り側が参加します。** オープンなトラッカー名前空間への `role: "viewer"` を指定した `namespace.join` は、サービスアカウントを含め、即座に承認されます。制限付きの名前空間は、その管理者の承認を待ち、読み取り側のトークンがその名前空間を指定する必要があります([ID と名前空間](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md))。 + +6. **トラッカーをリポジトリにリンクします。** これにより、そのチェックアウトで作業するエージェントがトラッカーを読めるようになります。方法は、`tracker_namespaces` を指定した `code.repo.set_source`(リポジトリの `admin`)、ダッシュボードのリポジトリカード、またはオペレーター自身のリポジトリに限り `LOOM_TRACKER_CODE_NAMESPACE_BINDINGS_JSON` です。1 つのリポジトリに複数のトラッカーを順番にリンクでき、最初のものがプライマリで、その番号がリポジトリの issue 番号と PR 番号になります([トラッカーのリンク](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/overview.md#linking-a-tracker-to-a-repository))。`tracker.binding` は、コード名前空間が呼び出し元に対して何に解決されるかを返します。 + + + +## 設定 + +同じエントリのオペレーター向けの形式: + +```bash +LOOM_TRACKER_ORG=acme +LOOM_TRACKER_SOURCES_JSON='{ + "sources": { + "widgets": {"host": "abc.clickhouse.cloud", "port": 8443, "secure": true, "database": "loom_tracker"} + }, + "namespaces": { + "tracker-widgets": {"source": "widgets", "repos": ["acme/widgets"]}, + "tracker-widgets-private": {"source": "widgets", "repos": ["acme/widgets-private"], "restricted": true} + } +}' +LOOM_TRACKER_CREDENTIALS_JSON='{"widgets": {"user": "loom_ro", "password": "…"}}' +LOOM_TRACKER_CODE_NAMESPACE_BINDINGS_JSON='{"code-widgets*": ["tracker-widgets", "tracker-helpdesk"]}' +``` + +認証情報はマップとは別の変数に置くため、シークレットを含めずにマップを表示したり差分を取ったりできます。バインディングの値は、1 つのトラッカー名前空間、または先頭をプライマリとする順序付きのリストです。キーはオペレーターのリポジトリのコード名前空間名に対する glob です(セルフサービスのリポジトリは、そのメンテナーがリンクします)。メンテナーが行う `code.repo.set_source` のリンクは、そのリポジトリについてはマップを置き換えます。トラッカー名前空間は `LOOM_TRACKER_ORG` に属します。これが空の場合、トラッカー名前空間は一切提供されません。 + + + +### ソースエントリのオプション + +ソースエントリには、次の項目も指定できます。 + +- `"mapping"`:保存済みのマッピング([マッピングモード](#mapping-mode))。指定がない場合はビューモードになります。 +- `"checks": {"from": "", "repo": "Org/repo"}`:トラッカーの CI 結果が置かれている場所で、`tracker.flaky` と `tracker.test_signal` が読み取ります。解決順序は、このエントリ、次にソース自身の `checks` テーブル、最後に `LOOM_TRACKER_CHECKS_FROM` / `LOOM_TRACKER_CHECKS_REPO`(どちらもデフォルトは空で、CI チェックなしを意味します)です。テーブル関数を包んだビューではなく、テーブル関数そのものを指定してください。ビューのフィルターはスキャンの後にリモート側で実行されるためです。`repo` を指定しない場合、リポジトリが 1 つだけの名前空間はそのリポジトリを使います。 +- `"bisect": {"code_prefixes": ["src/"]}`:bisect でソースコードとみなすパスです。指定がない場合は、docs、tests、CI、examples、benchmarks のいずれの配下でもないすべてのパスが対象です。トラッカーのないリポジトリでも、Loom 自身の PR 履歴に対して bisect を行います(その場合、回答には `candidates_from: "code_history"` が含まれます)。 +- `"columns": {"
": {"": ""}}`:お使いのテーブルが別の名前で持っているコントラクトのカラムです。たとえば `{"github_issues": {"triage_bisect_outcome": "bisect_result"}}` のように指定します。実際のカラムも、対応するコントラクトのカラムと同様に検査されます。使用できるのは単純な識別子のみです。 + +ルール: + +- 未知のソースを指定した名前空間は提供されません(起動時にエラーを 1 行出力するだけで、推測はしません)。 +- 各ソースは独自の接続、サーキットブレーカー、時間予算を持つため、あるチームのサービスが遅くなっても、他のチームのブレーカーが作動することはありません。 +- 登録済みのソース(`loom.qa_sources`)は `LOOM_TRACKER_SOURCES_REFRESH_SECONDS`(60)秒ごとに再読み込みされます。同じプロセス内での書き込みは、すぐに反映されます。 + +トラッカーの全設定は[設定リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#tracker)にあります。 + + + +## 公開と非公開 + +トラッカーの名前空間は **standard** または **restricted** のいずれかで、Loom がステートメントごとに強制します。 + +- standard 名前空間では、すべてのステートメントに `is_private = 0` が付与されます。非公開データのみを保持するテーブル(`core_incidents`、`support_cases`、`slack_threads`)は、読み取りの前に拒否されます。 +- restricted 名前空間ではこの述語が外れ、その名前空間自身の `repos` のみを読み取ります。アクセスは restricted 名前空間のルールによって制御され、その名前空間を指定するトークンと直接の許可(grant)が必要です。 + +次の 3 つの構成が使えます。 + +- `is_private` 列を持つ 1 組のビューを用意し、両方の名前空間から読み取る構成(読み取り専用ユーザーに対して `is_private` の行ポリシーを設定すると、ClickHouse 側でも確認が加わります)。 +- 2 組のビューと 2 人のユーザーを用意し、一方は公開行のみを保持させ、2 つのソースとして登録する構成。 +- restricted 名前空間のみの構成。 + + + +## 契約 + +型は**ファミリー**単位で比較します。`String`、`LowCardinality(String)`、`Nullable(String)`、`FixedString`、`Enum` は同一ファミリー、`DateTime`、`DateTime64`、`Date` は同一ファミリー、`UInt*` と `Int*` の各型と `Bool` は同一ファミリーです。`Array(x)` は `x` で比較します。別のストアに対するビューは、コーデックや null 許容性が異なっていてもかまいませんが、構造が異なってはいけません。ビューテンプレートでは、各ファミリーを最も幅の広い型(`UInt64`、`DateTime64(3)` など)で記述します。 + + + +### 必須テーブル + +これらがないソースは提供されません。 + +**`github_issues`**:issue ごとに 1 行です。 + +| カラム | ファミリー | 意味 | +| -------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `id` | UUID | `uuid5(NAMESPACE_DNS, 'github_issue:' \|\| source_id)`(プライベート行では `github_issue_private:`)。`edges` が使うキーです | +| `source_id` | String | `Org/repo#number`。リポジトリは tracker 名前空間に列挙されているものでなければなりません | +| `number` | UInt | issue 番号 | +| `url`, `title`, `body`, `author` | String | 人が開けるリンク、すべての検索が読むタイトル、重複チェックが読むテキスト、issue を作成した人 | +| `labels`, `assignees` | Array(String) | | +| `primary_component`, `severity_level` | String | チームの分類体系。ない場合は `''` | +| `state_reason` | String | `completed`、`not_planned`、`duplicate`、または `''` | +| `affected_versions`, `fix_versions` | Array(String) | issue が影響するバージョン、修正を含むバージョン | +| `is_flaky_test`, `is_crash_ci`, `is_performance` | UInt | 0/1 のフラグ。不明な場合は `0` | +| `has_test` | UInt | 関連するテストがあるか。不明な場合は NULL | +| `error_code` | UInt | 報告が示すサーバーのエラーコード。ない場合は `0` | +| `is_private` | UInt | プライベートリポジトリの行では `1` | +| `created_at`, `updated_at`, `closed_at` | DateTime | `closed_at` は未クローズの間はエポック 0 | +| `triage_bisect_outcome`, `triage_introduced_commit`, `triage_component`, `triage_confidence` | String | トリアージボットの判定。tracker にない場合は `''` として提供されます | +| `triage_reproduces_on`, `triage_clean_on` | Array(String) | 同様に、ない場合は `[]` として提供されます | + +**`github_prs`**:プルリクエストごとに 1 行です。 + +| カラム | ファミリー | 意味 | +| -------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------- | +| `id` | UUID | `uuid5(NAMESPACE_DNS, 'github_pr:' \|\| source_id)`(`github_pr_private:`) | +| `source_id`, `number`, `url`, `title`, `body`, `author` | 上記と同じ | | +| `pr_number` | UInt | `number` と同じ | +| `primary_component`, `severity_level`, `is_private`, `created_at`, `updated_at`, `closed_at` | 上記と同じ | | +| `state` | String | `open`、`closed`、または `merged` | +| `is_merged`, `has_test`, `review_requests_test` | UInt | | +| `test_types`, `reviewers`, `src_components` | Array(String) | | +| `ci_result`, `changelog_category`, `minor_version`, `base_branch` | String | | +| `is_backport_pr`, `is_cherrypick_pr`, `is_sync_pr` | UInt | 派生 PR。アクティビティの読み取りからは除外されます | +| `upstream_pr_number` | UInt | バックポートが繰り返す元の PR。ない場合は `0` | +| `additions`, `deletions`, `time_to_merge_days` | UInt | | + +**`edges`**:アイテム間のリンクです。 + +| カラム | ファミリー | 意味 | +| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | +| `from_id`, `to_id` | UUID | 上記のアイテム id | +| `from_type`, `to_type` | String | `github_issue`, `github_pr`, `github_issue_private`, `github_pr_private`, `core_incident`, `support_case` | +| `rel_type` | String | `fixes`, `related_to`, `duplicate_of`, `caused_by`, `backport_of`, `reverts`, … | +| `created_at` | DateTime | | + +Loom はアイテムの `id` をローカルで導出し、それをキーに `edges` を結合するため、ビューはまったく同じ値を生成する必要があります。ClickHouse には `uuid5()` がありません。`tracker.contract` が返す `loom_uuid5` 関数は、RFC 4122 のバージョン 5 の構成を SQL で実装したもので、Python の `uuid.uuid5` と同じ値になります。 + + + +### 任意テーブル + +テーブルがない場合、それを必要とする op は `not_provided` を返します。テーブルはあっても最小カラム(`contract.py` の `OPTIONAL`)のいずれかが欠けている場合は `incomplete` と報告され、ないものとして扱われます。 + +| テーブル | 最小カラム | +| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `core_incidents` | `id`, `source_id`, `title`, `body`, `primary_component`, `severity_level`, `stack_functions Array(String)`(スタックフレームの照合), `error_code`, `created_at` | +| `support_cases` | `id`, `source_id`, `title` | +| `slack_threads` | `source_id`, `title`, `body` | +| `component_risk_snapshot` | `computed_at`, `component` | +| `release_items` | `release_version`, `issue_number` | +| `release_health_snapshot` | `computed_at`, `release_version` | +| `version_history`, `version_history_private` | `commit_sha`, `version` | +| `checks` | `check_name`, `test_name` | +| `cloud_instances` | `instance_id` | +| `rel_instance_mentions` | `from_id`, `instance_id` | +| `slack_incidents` | `incident_id` | + +`core_incidents`、`support_cases`、`slack_threads` は、制限付きの名前空間を通してのみ読み取られます。 + + + +### 機能カラム + +必須テーブル上の任意カラムで、存在するか存在しないかが報告されます。ソースにない機能カラムは、そのエイリアス、なければデフォルトとして読み取られます([エイリアス](#aliases)を参照)。それを読むステートメントは、そのカラムを持たない行に対するものとして応答し、機能は存在しないままになります。 + +| 機能 | カラム | 有効になるもの | +| ------------ | --------------------------------------------------- | --------------------------------------------------------------------------------- | +| `bisect` | `github_prs.diff`, `github_prs.affected_file_paths` | bisect 候補と原因コミットのスキャン | +| `merge_time` | `github_prs.merged_at` | マージ時間に関する事実 | +| `vector` | `github_issues.embedding`, `github_prs.embedding` | 報告のみ。`tracker.similar` は Loom 自身が計算する埋め込みを使用します | + + + +### エイリアス + +ソースに契約のカラムがない場合でも、`contract.py` の `ALIASES` が、そのソースにあるカラム上で受け入れ可能な式を指定していれば、契約を満たします。チェックはエイリアス自身のカラムをファミリーで検証し、`aliased` として報告します。ステートメントは引き続き契約上の名前を読みます。テーブル参照が、エイリアスを追加する射影に置き換えられるためです(クエリアナライザーが、ステートメントが読むカラムに絞り込みます)。自身のカラムを持たないエイリアスは**デフォルト**(`defaulted`)です。すべての行が `''`、`0`、`[]`、`NULL` のいずれかとして読まれ、レポートにもその旨が示されるため、デフォルトがデータと取り違えられることはありません。 + +| テーブル | カラム | 受け入れられる形式(順序どおり) | +| ------------------------------------------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | +| `github_issues` | `severity_level` | `severity` | +| `github_issues` | `has_test` | `toUInt8(metadata.has_test.:Bool)`(JSON の `metadata` カラム)、なければ `NULL` | +| `github_issues` | `triage_bisect_outcome`, `triage_introduced_commit`, `triage_component`, `triage_confidence` | `''` | +| `github_issues` | `triage_reproduces_on`, `triage_clean_on` | `[]` | +| `github_prs` | `has_test` | `toUInt8(metadata.has_test.:Bool)`、なければ `toUInt8(tests_added > 0)` | +| `github_prs` | `upstream_pr_number` | `ifNull(toUInt32(metadata.original_pr_number.:Int64), 0)`、なければ `0` | +| `github_prs` | `review_requests_test` | `NULL` | +| `github_prs` | `test_types`, `src_components` | `[]` | +| `github_prs` | `merged_at` | `if(is_merged = 1, closed_at, toDateTime64(0, 3))` | +| `github_prs`, `core_incidents` | `severity_level` | `''` | +| `qa_bugs`(回答ルートのクロスソースビュー) | `severity_level`, `has_test` | `severity`、`toUInt8(metadata.has_test.:Bool)`、なければ `NULL` | + +契約に載っていないリネームは、依然としてカラム欠落として扱われます。ソースエントリの `columns` マップ([ソースエントリのオプション](#source-entry-options))で宣言するか、`contract.py` に `Alias` を追加して、すべてのソースで別の表記を受け入れるようにしてください。 + + + +## マッピングモード + +マッピングは、論理テーブルごとに、チームのどのテーブルを読み取るかを指定し、論理カラムごとに、そのテーブルのカラムに対する式を指定します。 + +```json +{ + "version": 1, + "tables": { + "github_issues": { + "source": "tracker_db.tickets", + "final": true, + "columns": { + "source_id": { "concat": [{ "lit": "acme/widgets#" }, "ticket_no"] }, + "number": "ticket_no", + "title": "summary", + "body": "description", + "created_at": "opened_at", + "state_reason": { "lower": "resolution" } + } + } + } +} +``` + +- **式はデータであり、SQL ではありません**:実テーブルが持つカラム名(または `{"col": …}`)、`{"lit": …}`、あるいは `concat`、`coalesce`、`eq`、`in`、`has`、`cast`(`[expr, family]`)、`lower`、`digits`(キー末尾の数字。`PROJ-1234` → `1234`)のいずれかです。Loom は識別子をバッククォートで、リテラルを引用符で囲んで式を生成し、各式をステートメントが読み取るファミリーに変換して、読み取り専用の認証情報で実行します。 +- `source` は `db.table` で指定します。トラッカーのデータベース内のテーブルであれば `table` だけで指定できます。`final: true` を指定すると、テーブルを `FINAL` 付きで読み取ります(Replacing、Collapsing、Aggregating、Summing の各エンジンで提案されます)。 +- Loom は、マッピングされた `source_id` から各アイテムの `id` を、マッピングされた `from_ref` / `to_ref`(`Org/repo#number`)からエッジの `from_id` / `to_id` を導出します。これらはマッピングしません。 +- マッピングする各テーブルには、コアカラムが必要です。`github_issues` は `source_id`、`number`、`title`、`created_at`、`github_prs` は `source_id`、`pr_number`、`title`、`created_at`、`edges` は `from_ref`、`to_ref`、`from_type`、`to_type`、`rel_type`、`core_incidents` は `source_id`、`title`、`created_at` です。マッピングでは `github_issues` を必ずマッピングしてください。マッピングされていないカラムにはデフォルト値が入るか、値が導出されます(PR の `state` はマージ済みとクローズ済みのフィールドから導出されます)。レポートにはそれらが一覧表示されます。マッピングで指定されていない論理テーブルは、空のテーブルとして読み取られます。 +- レポートの capabilities(`items`、`duplicate_check`、`duplicate_calibration`、`pull_requests`、`links`、`severity_board`、`bisect`、`incidents`、`ci_checks`)は、マッピングされたデータで Loom が何に答えられるかを示します。 + +読み取り時には、各論理テーブルへの参照がマッピングされたプロジェクションに置き換えられるため、すべてのソースに対して同じステートメント、テスト、プライバシー述語が実行されます。 + + + +## ソースの確認 + +```bash +loom tracker-contract-check # every configured source +loom tracker-contract-check --source widgets # one source +loom tracker-contract-check --namespace tracker-widgets +loom tracker-contract-check --json +``` + +サーバーは、プロセスごとの最初のトラッカー読み取り時に同じチェックを実行します。ソース自身の認証情報でスキーマを読み取り(`system.columns`、それが非表示の場合はテーブルごとの `DESCRIBE`)、結果を `LOOM_TRACKER_CONTRACT_TTL_S`(3,600 秒)のあいだキャッシュします。失敗した結果は 60 秒だけキャッシュするため、修正したビューは 1 分以内に反映されます。チェックに失敗したソースは、不足している内容を示す `tracker_unavailable` をすべての読み取りに返し、部分的な応答は返しません。`tracker.source.check` を使うと、チェックをオンデマンドで実行できます。 + + + +## 関連ドキュメント + +- [トラッカーの概要](https://github.com/ClickHouse/loom/blob/main/docs/features/tracker/overview.md):各 op が答える内容、リンク、ダッシュボードのフロー +- [履歴と PR](https://github.com/ClickHouse/loom/blob/main/docs/features/code-index/history-and-prs.md):トラッカーを読み取るコードプレーンの op +- [設定リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md#tracker) +- [操作リファレンス](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#tracker) diff --git a/i18n/ko/docs/architecture/agno-adapter.md b/i18n/ko/docs/architecture/agno-adapter.md new file mode 100644 index 0000000000..a4e019f463 --- /dev/null +++ b/i18n/ko/docs/architecture/agno-adapter.md @@ -0,0 +1,25 @@ + +> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/architecture/agno-adapter.md)을 기계 번역한 것이며, 영어 원문이 기준입니다. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/agno-adapter.md), which is authoritative. + + + +# Agno 사용자 메모리 데이터베이스 + +Agno 어댑터는 동기식 Loom SDK를 통해 3.2 `BaseDb` 인터페이스의 사용자 메모리 메서드를 구현합니다. 마이너 버전이 고정된 선택적 의존성은 코어 SDK와 서버에 포함되지 않습니다. `MemoryManager`는 에이전트의 세션 데이터베이스와 별개로 이 데이터베이스를 받아들입니다. 메모리와 관련 없는 기능은 프레임워크 기본 저장소를 사용하지 않고 요청을 거부합니다. + + + +## 불변 조건 + +각 어댑터는 사용자와 애플리케이션 저장소를 바인딩합니다. 모든 SDK 호출에는 해당 사용자와 그로부터 파생된 세션이 포함되며, 키에는 동일한 스코프 다이제스트와 네이티브 id 다이제스트가 들어 있습니다. 명시적으로 지정한 다른 사용자는 거부됩니다. 네이티브 사용자 메모리는 에피소드 Loom 행에 JSON으로 저장되며, 서로 다른 네이티브 레코드를 의미적으로 병합하지 않고 id, 메타데이터, 리비전을 그대로 보존합니다. 액터와 소스의 출처 정보는 Loom의 일반 쓰기 경로에서 가져옵니다. 일반 메모리 삭제, 소거, 롤링 스키마 규칙이 그대로 적용됩니다. + +목록 조회는 개수가 제한되고 필요한 필드만 담은 페이지를 따라가며, 겹치는 항목은 중복을 제거하고, 잘린 값은 네이티브 객체로 변환하기 전에 다시 가져와 채웁니다. 콘텐츠, 토픽, 귀속 필터와 정렬, 페이지네이션, 통계는 이처럼 사용자/저장소 범위로 한정된 스냅샷에 대해 실행됩니다. 로컬 영구 상태는 없습니다. 동시에 수정하면 서버에 마지막으로 기록된 쓰기가 유지되며, 일괄 작업은 쓰기를 순차적으로 수행하는 방식이므로 실패 시 일부만 완료될 수 있습니다. 서로 신뢰하지 않는 애플리케이션은 네임스페이스 권한 부여로 격리합니다. + + + +## 소스 진입점 + +- `sdk/python/loom/integrations/agno.py`: `LoomMemoryDb`. +- `sdk/python/tests/test_agno.py`: 네이티브 메모리 관리자 동작. +- `tests/integration/test_sdk_agno_memory.py`: 실제 환경에서의 메모리 스코프와 출처 정보. diff --git a/i18n/ko/docs/architecture/google-adk-adapter.md b/i18n/ko/docs/architecture/google-adk-adapter.md new file mode 100644 index 0000000000..758cbae7ef --- /dev/null +++ b/i18n/ko/docs/architecture/google-adk-adapter.md @@ -0,0 +1,26 @@ + +> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/architecture/google-adk-adapter.md)을 기계 번역한 것이며, 영어 원문이 기준입니다. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/google-adk-adapter.md), which is authoritative. + + + +# Google ADK 메모리 서비스 + +Google ADK 어댑터는 Loom의 Python 및 TypeScript SDK를 통해 프레임워크의 메모리 서비스를 구현합니다. 프레임워크 패키지는 선택적 의존성입니다. 지식 문서는 해당 네임스페이스의 모든 독자와 공유되므로, 모든 애플리케이션은 별도의 Loom 네임스페이스를 사용합니다. + +세션 쓰기는 활성 상태인 사용자 및 모델 이벤트에서 텍스트를 추출하고(도구 페이로드와 thought는 제외), 제한된 크기의 배치로 `memory.set_from_messages`를 호출합니다. 두 SDK 모두 비어 있거나, 센티널 값이거나, 공백이 덧붙은 사용자 id는 어떤 호출보다 먼저 거부합니다. 각 호출에는 최종 사용자와, 사용자 및 네이티브 세션 id에서 파생한 세션이 포함됩니다. Python은 설치된 프레임워크의 증분 이벤트, 직접 메모리, 삭제 메서드도 구현합니다. Python 삭제 id에는 키, 세션, 작성자, 정확한 버전이 담기며, 이 id로 `memory.delete_version`을 직접 호출합니다. 존재하지 않거나 다시 쓰인 버전은 아무 동작도 하지 않으며, 다른 작성자의 행은 선택되지 않습니다. 메모리 검색 히트의 추가 응답 필드 `agent`는 보관된 행의 식별 정보에서 가져오며, 보류된 페이지도 포함합니다. 작성자나 버전을 알 수 없는 히트에는 삭제 id가 없습니다. 이전 클라이언트는 추가 필드를 무시하지만, 정확한 ADK 삭제를 쓰려면 이 필드를 제공하는 서버가 필요합니다. 이로 인해 영속 컬럼이나 마이그레이션이 추가되지는 않습니다. TypeScript는 작성자 범위의 참고용 id를 반환하며, 설치된 프레임워크 인터페이스에는 삭제 메서드가 없습니다. + +검색은 먼저 바인딩된 사용자에 대해 `memory.search`를 호출한 다음, 남은 결과 슬롯을 네임스페이스 범위의 `knowledge.search` 결과로 채웁니다. 지식은 비공개 사용자 메모리가 아니라 공유되는 애플리케이션 컨텍스트입니다. 두 SDK는 같은 다이제스트 인코딩을 사용하며, 프레임워크의 네이티브 타임스탬프 표현은 경계에서 변환됩니다. 서비스 인스턴스 하나는 애플리케이션 하나에 바인딩됩니다. 서로 신뢰하지 않는 애플리케이션은 네임스페이스 권한 부여(grant)로 격리합니다. + + + +## 소스 진입점 + +- `sdk/python/loom/integrations/google_adk.py`: `LoomMemoryService`. +- `sdk/typescript/src/integrations/google-adk.ts`: `LoomMemoryService`. + + + +## 불변 조건 + +서버는 일반적인 쓰기 경로를 통해 행위자와 소스 출처 정보를 제공합니다. 어댑터는 데이터베이스, 스키마, 프로바이더를 추가하지 않습니다. 기존의 메모리 삭제, 지식 삭제, 롤링 업그레이드 규칙이 그대로 적용됩니다. 시맨틱 추출은 사실을 수정할 수 있으므로, 이 서비스는 정확한 대화 기록 저장소가 아닙니다. 지식 결과에는 사용자 메모리 id가 없으며 메모리 서비스를 통해 삭제할 수 없습니다. diff --git a/i18n/ko/docs/architecture/haystack-adapter.md b/i18n/ko/docs/architecture/haystack-adapter.md new file mode 100644 index 0000000000..a9c60388dc --- /dev/null +++ b/i18n/ko/docs/architecture/haystack-adapter.md @@ -0,0 +1,27 @@ + +> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/architecture/haystack-adapter.md)을 기계 번역한 것이며, 영어 원문이 기준입니다. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/haystack-adapter.md), which is authoritative. + + + +# Haystack 문서 저장소와 리트리버 + +선택 사항인 Haystack 3.5 어댑터는 동기식 Loom SDK를 통해 문서 저장소 프로토콜과 네이티브 검색 컴포넌트를 구현합니다. 코어 SDK와 서버는 이 프레임워크에 의존하지 않습니다. 각 HTTP 호출은 SDK가 관리하는 클라이언트 수명을 가지며, 어댑터는 서버, 로컬 데이터베이스, 캐시, 영속적인 백그라운드 프로세스를 남기지 않습니다. + + + +## 불변 조건 + +저장소는 각 네이티브 문서 id를 저장소별 접두사 아래의 해시된 소스 URI에 매핑합니다. 일치하는 태그는 목록 조회와 검색의 범위를 지정합니다. 메타데이터, 임베딩, 바이너리 필드를 포함한 네이티브 문서 전체 직렬화는 문서의 원본 파일 바이트에 저장됩니다. 청크 메타데이터에는 작은 형식 마커만 들어 있으며, 텍스트는 문서 콘텐츠로 인덱싱되고 텍스트가 없으면 id가 인덱싱됩니다. Loom의 일반적인 문서 쓰기, 출처(provenance), 네임스페이스 권한 부여, 버전 관리, 삭제 경로가 모든 쓰기와 삭제에 적용됩니다. 문서는 사용자 전용이 아니라 네임스페이스 단위로 공유됩니다. + +개수 계산과 필터링은 커서 페이지를 통해 저장소 전체를 불러옵니다. 네이티브 필터 헬퍼가 비교와 불리언 논리를 적용합니다. 검색은 네임스페이스, 태그, URI 경계를 명시하여 최대 100개의 청크를 조회하고, 전체 문서를 불러온 뒤 소스 URI 기준으로 중복을 제거하며 각 문서에서 가장 높은 순위의 히트를 유지합니다. 이러한 작업에는 요청 간 스냅샷이 없습니다. 동시에 쓰기가 일어나면 Loom이 충돌을 반환할 수 있습니다. 중복 확인과 다중 문서 작업은 트랜잭션이 아닙니다. + +직렬화된 연결에는 Haystack 환경 변수 Secret 참조가 포함되며, 원시 Secret 토큰은 직렬화가 거부됩니다. 명시적인 엔드포인트 URL에는 내장된 시크릿을 넣을 수 없습니다. 어댑터는 Haystack의 파이프라인 역직렬화 신뢰 정책을 그대로 유지하며, 신뢰할 모듈을 등록하거나 안전하지 않은 역직렬화를 선택하지 않습니다. + + + +## 소스 진입점 + +- `sdk/python/loom/integrations/haystack.py`: `LoomDocumentStore`와 `LoomRetriever`. +- `sdk/python/tests/test_haystack.py`: 네이티브 문서 저장소 및 파이프라인 동작. +- `tests/integration/test_sdk_haystack.py`: 실제 환경에서의 문서 영속화 및 검색. diff --git a/i18n/ko/docs/reference/operations/working_memory.md b/i18n/ko/docs/reference/operations/working_memory.md new file mode 100644 index 0000000000..8cf076bed3 --- /dev/null +++ b/i18n/ko/docs/reference/operations/working_memory.md @@ -0,0 +1,179 @@ + +> 이 페이지는 [영어 원문](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/working_memory.md)을 기계 번역한 것이며, 영어 원문이 기준입니다. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/working_memory.md), which is authoritative. + + + +# `working_memory` 연산 + +각 `working_memory.*` 연산이 받고 반환하는 정확한 필드입니다. + + + +모든 연산은 HTTP에서는 `POST /v1/`이고 MCP 도구로는 `loom_`입니다. 신원 필드(`org`, `namespace`, `agent`, `user_id`, `session_id`)는 전송 방식이 가능한 경우 토큰과 MCP 세션에서 채워집니다. 단일 사용자 서버에서 토큰 없이 HTTP로 호출하면, `code.*`와 `tracker.*`(각자의 plane 값을 유지함)를 제외한 모든 연산에서는 설치의 org가 채워지고, [일부 연산](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)에서는 네임스페이스와 에이전트도 채워집니다. 자세한 내용은 [신원과 네임스페이스](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md)를 참고하세요. [연산 인덱스](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)에서 role, kind, MCP `all` 목록을 설명합니다. 알 수 없는 입력 필드는 그대로 처리되며 `ignored_args`에 이름이 표시됩니다. + + + + + +## `working_memory.append` + +워킹 메모리 블록의 끝에 텍스트를 추가하며, 블록이 없으면 새로 만듭니다. + +`POST /v1/working_memory.append` · MCP `loom_working_memory_append` · role `writer` · write + +| 입력 필드 | 타입 | 기본값 | 의미 | +| --- | --- | --- | --- | +| `org` | `str` | 필수 | 테넌트(identity 튜플의 첫 번째 요소). | +| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. | +| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. | +| `user_id` | `str` | `'-'` | 해당 행이 속한 최종 사용자. 없으면 `'-'`. | +| `session_id` | `str` | `'-'` | 해당 행이 속한 세션 또는 대화. 없으면 `'-'`. | +| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위). 없으면 `'-'`. | +| `block_key` | `str` | `'scratchpad'` | 내용을 추가할 블록. 블록이 없으면 기본 크기 제한으로 새로 만듭니다. | +| `addition` | `str` | 필수 | 블록 끝에 추가할 텍스트. | +| `separator` | `str` | `'\n'` | 기존 텍스트와 `addition` 사이에 넣는 구분자. 블록이 새로 만들어지는 경우에는 사용되지 않습니다. | + +| 출력 필드 | 타입 | 의미 | +| --- | --- | --- | +| `block_key` | `str` | 쓰기가 수행된 블록. | +| `version` | `int` | 이번 쓰기로 생성된 행의 버전(나노초 타임스탬프). | +| `char_limit` | `int` | 쓰기 이후 블록의 크기 제한(문자 수). | +| `value_length` | `int` | 쓰기 이후 블록 내용의 길이(문자 수). | +| `fill_ratio` | `float` | `value_length / char_limit` 값으로, 소수점 셋째 자리까지 표시합니다. 1.0을 넘게 되는 쓰기는 거부됩니다. | + + + +## `working_memory.delete` + +워킹 메모리 블록 하나를 삭제합니다. + +`POST /v1/working_memory.delete` · MCP `loom_working_memory_delete` · 역할 `writer` · 멱등 · MCP `all` 툴셋에는 나열되지 않음 + +| 입력 필드 | 타입 | 기본값 | 의미 | +| --- | --- | --- | --- | +| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소)입니다. | +| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스입니다. | +| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트입니다. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. | +| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자입니다. 없으면 `'-'`입니다. | +| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화입니다. 없으면 `'-'`입니다. | +| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위)입니다. 없으면 `'-'`입니다. | +| `block_key` | `str` | `'scratchpad'` | 삭제할 블록입니다. | + +| 출력 필드 | 타입 | 의미 | +| --- | --- | --- | +| `deleted` | `bool` | 해당 범위에 이 키의 유효한 블록이 없으면 False입니다. | +| `block_key` | `str` | 입력 `block_key`를 그대로 반환한 값입니다. | + + + +## `working_memory.get` + +키로 워킹 메모리 블록 하나를 가져옵니다. + +`POST /v1/working_memory.get` · MCP `loom_working_memory_get` · 역할 `viewer` · 읽기 · MCP `all` 툴셋에는 포함되지 않음 + +| 입력 필드 | 타입 | 기본값 | 의미 | +| --- | --- | --- | --- | +| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소). | +| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. | +| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. | +| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자. 없으면 `'-'`. | +| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화. 없으면 `'-'`. | +| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위). 없으면 `'-'`. | +| `block_key` | `str` | `'scratchpad'` | 호출자의 (agent, user, session, run) 범위 안에서 읽을 블록. | + +| 출력 필드 | 타입 | 의미 | +| --- | --- | --- | +| `found` | `bool` | 해당 범위에 이 키의 유효한 블록이 없으면 False이며, 이 경우 나머지 필드는 기본값입니다. | +| `block_key` | `str` | 블록 키를 그대로 반환한 값. | +| `content` | `str` | 블록의 텍스트. 찾지 못하면 비어 있습니다. | +| `char_limit` | `int` | 블록의 크기 상한(문자 수). 이를 넘기는 쓰기는 422로 거부됩니다. | +| `version` | `int` | 블록의 현재 행 버전(나노초 타임스탬프). 찾지 못하면 0. | +| `updated_at` | `datetime \| None` | 블록이 마지막으로 쓰인 시각. 찾지 못하면 None. | +| `fill_ratio` | `float` | len(content) / char_limit. | + + + +## `working_memory.render` + +워킹 메모리 블록을 XML 또는 마크다운으로 렌더링합니다. context.pack에는 이미 이 섹션이 포함되어 있으며, 직접 렌더링은 주로 SDK나 커스텀 오케스트레이션 코드에서 사용합니다. + +`POST /v1/working_memory.render` · MCP `loom_working_memory_render` · role `viewer` · read + +| 입력 필드 | 타입 | 기본값 | 의미 | +| --- | --- | --- | --- | +| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소)입니다. | +| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스입니다. | +| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트입니다. `'-'` 또는 `'*'`는 op가 허용하는 경우 모든 에이전트를 뜻합니다. | +| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자입니다. 없으면 `'-'`입니다. | +| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화입니다. 없으면 `'-'`입니다. | +| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위)입니다. 없으면 `'-'`입니다. | +| `block_keys` | `list[str]` | *(계산됨)* | 지정한 블록만 대상으로 합니다(최대 20개). 비어 있으면 범위 내의 모든 활성 블록입니다. | +| `format` | `Literal['xml', 'markdown']` | `'xml'` | `xml`은 각 블록을 `` 태그로 감싸고, `markdown`은 `## ` 제목 아래에 넣습니다. | +| `limit` | `int` | `20` | `block_key` 순서로 최대 이 개수만큼의 블록을 반환합니다(1-100). | + +| 출력 필드 | 타입 | 의미 | +| --- | --- | --- | +| `rendered` | `str` | 선택한 `format`으로 만든 하나의 텍스트입니다. 범위에 블록이 없으면 비어 있습니다. | +| `blocks` | `list[WorkingMemoryBlock]` | 렌더링된 블록과 크기 제한 및 버전 정보이며, `block_key` 순서입니다. | +| `block_count` | `int` | 렌더링된 블록 수입니다. | +| `total_chars` | `int` | 블록 콘텐츠 길이의 합계이며, 문자 단위입니다. | + + + +## `working_memory.replace` + +워킹 메모리 블록 안의 정확히 일치하는 텍스트를 교체합니다. + +`POST /v1/working_memory.replace` · MCP `loom_working_memory_replace` · 역할 `writer` · 멱등 · MCP `all` 툴셋에는 나열되지 않음 + +| 입력 필드 | 타입 | 기본값 | 의미 | +| --- | --- | --- | --- | +| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소)입니다. | +| `namespace` | `str` | 필수 | 이 op가 읽거나 쓰는 네임스페이스입니다. | +| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트입니다. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. | +| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자입니다. 없으면 `'-'`입니다. | +| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화입니다. 없으면 `'-'`입니다. | +| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위)입니다. 없으면 `'-'`입니다. | +| `block_key` | `str` | `'scratchpad'` | 편집할 블록입니다. 블록이 없으면 404입니다. | +| `old` | `str` | 필수 | 찾을 텍스트입니다. 일치하는 모든 항목이 교체되며, 텍스트가 없으면 422입니다. | +| `new` | `str` | `''` | 대체할 텍스트입니다. 비어 있으면 `old`와 일치하는 항목이 삭제됩니다. | + +| 출력 필드 | 타입 | 의미 | +| --- | --- | --- | +| `block_key` | `str` | 기록된 블록입니다. | +| `version` | `int` | 이 쓰기가 생성한 행의 버전입니다(나노초 타임스탬프). | +| `char_limit` | `int` | 쓰기 이후 블록의 크기 상한(문자 수)입니다. | +| `value_length` | `int` | 쓰기 이후 블록 내용의 길이(문자 수)입니다. | +| `fill_ratio` | `float` | `value_length / char_limit`을 소수점 셋째 자리까지 나타낸 값입니다. 1.0을 넘게 되는 쓰기는 거부됩니다. | + + + +## `working_memory.set` + +워킹 메모리 블록 하나를 덮어씁니다. + +`POST /v1/working_memory.set` · MCP `loom_working_memory_set` · role `writer` · 멱등 + +| 입력 필드 | 타입 | 기본값 | 의미 | +| --- | --- | --- | --- | +| `org` | `str` | 필수 | 테넌트(식별 튜플의 첫 번째 요소). | +| `namespace` | `str` | 필수 | op가 읽거나 쓰는 네임스페이스. | +| `agent` | `str` | 필수 | 쓰거나 읽는 에이전트. op가 허용하는 경우 `'-'` 또는 `'*'`는 모든 에이전트를 의미합니다. | +| `user_id` | `str` | `'-'` | 행이 속한 최종 사용자. 없으면 `'-'`. | +| `session_id` | `str` | `'-'` | 행이 속한 세션 또는 대화. 없으면 `'-'`. | +| `run_id` | `str` | `'-'` | 호출이 속한 에이전트 실행(작업 범위). 없으면 `'-'`. | +| `block_key` | `str` | `'scratchpad'` | 쓸 블록. 호출자의 (agent, user, session, run) 범위 안에서 지정합니다. | +| `content` | `str` | `''` | 기존 내용을 대체할 블록의 전체 새 텍스트. 비어 있으면 빈 블록을 저장합니다. | +| `char_limit` | `int` | `4096` | 블록의 크기 상한(문자 수). 이보다 긴 `content`는 422로 거부됩니다. | + +| 출력 필드 | 타입 | 의미 | +| --- | --- | --- | +| `block_key` | `str` | 쓰기가 수행된 블록. | +| `version` | `int` | 이 쓰기로 생성된 행의 버전(나노초 타임스탬프). | +| `char_limit` | `int` | 쓰기 이후 블록의 크기 상한(문자 수). | +| `value_length` | `int` | 쓰기 이후 블록 내용의 길이(문자 수). | +| `fill_ratio` | `float` | `value_length / char_limit`, 소수점 셋째 자리까지. 1.0을 넘는 쓰기는 거부됩니다. | + + diff --git a/i18n/pt-BR/docs/architecture/agno-adapter.md b/i18n/pt-BR/docs/architecture/agno-adapter.md new file mode 100644 index 0000000000..8e360f403b --- /dev/null +++ b/i18n/pt-BR/docs/architecture/agno-adapter.md @@ -0,0 +1,41 @@ + +> Esta página é uma tradução automática da [página em 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. + + + +# Banco de dados de memória de usuário do Agno + +O adaptador do Agno implementa os métodos de memória de usuário da sua interface `BaseDb` 3.2 +por meio do SDK síncrono do Loom. A dependência opcional, fixada na versão minor, fica fora +do SDK principal e do servidor. O `MemoryManager` aceita esse banco de dados independentemente +do banco de dados de sessão de um agente. Capacidades que não envolvem memória são recusadas +em vez de usar um armazenamento padrão do framework. + + + +## Invariantes + +Cada adaptador vincula um usuário e um armazenamento da aplicação. Toda chamada ao SDK carrega +esse usuário e uma sessão derivada; as chaves incluem o mesmo digest de escopo mais um digest +do id nativo. Um usuário explícito diferente é recusado. As memórias de usuário nativas são +JSON em linhas episódicas do Loom, preservando ids, metadados e revisões sem mesclagem +semântica de registros nativos diferentes. A procedência de ator e de origem vem do caminho +normal de escrita do Loom. Aplicam-se as regras comuns de exclusão de memória, apagamento e +esquema contínuo. + +A listagem segue páginas limitadas e projetadas, remove duplicatas de sobreposição e hidrata +valores truncados antes de convertê-los em objetos nativos. Filtros de conteúdo, tópicos e +atribuição, ordenação, paginação e estatísticas são executados sobre esse snapshot de +usuário/armazenamento com escopo definido. Não há estado persistente local. Edições +concorrentes mantêm a última escrita do servidor; operações em lote são uma sequência de +escritas e podem terminar parcialmente em caso de falha. Concessões de namespace isolam +aplicações que não confiam umas nas outras. + + + +## Pontos de entrada no código-fonte + +- `sdk/python/loom/integrations/agno.py`: `LoomMemoryDb`. +- `sdk/python/tests/test_agno.py`: comportamento nativo do gerenciador de memória. +- `tests/integration/test_sdk_agno_memory.py`: escopo de memória e procedência em ambiente real. diff --git a/i18n/pt-BR/docs/architecture/google-adk-adapter.md b/i18n/pt-BR/docs/architecture/google-adk-adapter.md new file mode 100644 index 0000000000..3a8b235f1a --- /dev/null +++ b/i18n/pt-BR/docs/architecture/google-adk-adapter.md @@ -0,0 +1,50 @@ + +> Esta página é uma tradução automática da [página em 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. + + + +# Serviço de memória do Google ADK + +O adaptador do Google ADK implementa o serviço de memória do framework por meio dos +SDKs de Python e TypeScript do Loom. Os pacotes do framework são dependências opcionais. Cada +aplicação usa um namespace do Loom separado, porque seus documentos de conhecimento são +compartilhados com todos os leitores desse namespace. + +As gravações de sessão extraem o texto dos eventos ativos do usuário e do modelo, excluindo payloads de +ferramentas e pensamentos, e então chamam `memory.set_from_messages` em lotes limitados. +Os dois SDKs recusam ids de usuário vazios, sentinela ou com espaços nas bordas antes de qualquer chamada. +Cada chamada carrega o usuário final e uma sessão derivada do usuário e do id de sessão +nativo. O Python também implementa os métodos de eventos incrementais, memória direta +e exclusão do framework instalado. Os ids de exclusão do Python carregam a chave, a sessão, +o escritor e a versão exata. Eles chamam `memory.delete_version` diretamente. Uma versão ausente ou +reescrita é uma operação nula (no-op), e +a linha de outro escritor nunca é selecionada. O campo de resposta aditivo `agent` nos +resultados de busca de memória vem da identidade da linha armazenada, incluindo páginas estacionadas. +Um resultado sem escritor ou versão conhecidos não tem id de exclusão. Clientes mais antigos ignoram +o campo extra; a exclusão exata do ADK exige um servidor que o forneça. Isso não adiciona +nenhuma coluna persistida nem migração. O TypeScript retorna ids informativos com escopo de escritor; +a interface do framework instalada não tem método de exclusão. + +A busca primeiro chama `memory.search` para o usuário vinculado e depois preenche os espaços de resultado +disponíveis com `knowledge.search` no escopo do namespace. O conhecimento é contexto compartilhado da aplicação, +não memória privada do usuário. Os dois SDKs usam a mesma codificação de digest; a +representação nativa de timestamp do framework é convertida na fronteira. Uma instância do serviço +é vinculada a uma aplicação. As concessões de namespace isolam aplicações que não confiam entre si. + + + +## Pontos de entrada no código-fonte + +- `sdk/python/loom/integrations/google_adk.py`: `LoomMemoryService`. +- `sdk/typescript/src/integrations/google-adk.ts`: `LoomMemoryService`. + + + +## Invariantes + +O servidor fornece a proveniência de ator e de origem por meio de seu caminho de gravação comum. +O adaptador não adiciona banco de dados, esquema nem provedor. As regras existentes de exclusão de memória, +apagamento de conhecimento e atualização contínua (rolling upgrade) se aplicam. A extração semântica pode revisar +fatos; este serviço não é um armazenamento exato de transcrições. Os resultados de conhecimento não têm id de +memória de usuário e não podem ser excluídos por meio do serviço de memória. diff --git a/i18n/pt-BR/docs/architecture/haystack-adapter.md b/i18n/pt-BR/docs/architecture/haystack-adapter.md new file mode 100644 index 0000000000..cee95b2e5f --- /dev/null +++ b/i18n/pt-BR/docs/architecture/haystack-adapter.md @@ -0,0 +1,27 @@ + +> Esta página é uma tradução automática da [página em 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. + + + +# Document store e retriever do Haystack + +O adaptador opcional do Haystack 3.5 implementa o protocolo de document store do framework e um componente nativo de recuperação por meio do SDK síncrono do Loom. O SDK principal e o servidor não dependem do framework. Cada chamada HTTP tem um ciclo de vida de cliente gerenciado pelo SDK; o adaptador não deixa servidor, banco de dados local, cache ou processo persistente em segundo plano. + + + +## Invariantes + +Um store mapeia cada id de documento nativo para uma URI de origem com hash, sob um prefixo específico do store. Uma tag correspondente delimita a listagem e a recuperação. A serialização nativa completa do documento, incluindo metadados, embeddings e campos binários, fica nos bytes do arquivo original do documento. Os metadados dos chunks carregam apenas um pequeno marcador de formato; o texto é indexado como conteúdo do documento, ou como o id quando não há texto. Os caminhos normais do Loom para escrita de documentos, proveniência, concessões de namespace, versionamento e apagamento se aplicam a toda escrita e exclusão. Os documentos são compartilhados no namespace, e não privados por usuário. + +A contagem e a filtragem carregam o store inteiro por meio de páginas com cursor. Os helpers de filtro nativos aplicam comparações e lógica booleana. A recuperação busca até 100 chunks com limites explícitos de namespace, tag e URI, carrega os documentos completos e remove duplicatas por URI de origem, preservando o resultado mais bem classificado de cada documento. Essas operações não têm snapshot entre requisições. Escritas concorrentes podem receber um conflito do Loom. As verificações de duplicidade e as operações com vários documentos não são transações. + +As conexões serializadas carregam referências Secret de variáveis de ambiente do Haystack; tokens Secret brutos recusam a serialização. URLs de endpoint explícitas rejeitam segredos embutidos. O adaptador preserva a política de confiança do Haystack para desserialização de pipelines e nunca registra módulos confiáveis nem seleciona a desserialização insegura. + + + +## Pontos de entrada no código-fonte + +- `sdk/python/loom/integrations/haystack.py`: `LoomDocumentStore` e `LoomRetriever`. +- `sdk/python/tests/test_haystack.py`: comportamento nativo do document store e do pipeline. +- `tests/integration/test_sdk_haystack.py`: persistência e recuperação de documentos em ambiente real. diff --git a/i18n/zh-CN/docs/architecture/agno-adapter.md b/i18n/zh-CN/docs/architecture/agno-adapter.md new file mode 100644 index 0000000000..edeb8afcbe --- /dev/null +++ b/i18n/zh-CN/docs/architecture/agno-adapter.md @@ -0,0 +1,25 @@ + +> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/agno-adapter.md)翻译,内容以英文原文为准。 +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/agno-adapter.md), which is authoritative. + + + +# Agno 用户记忆数据库 + +Agno 适配器通过同步的 Loom SDK 实现其 3.2 版 `BaseDb` 接口中的用户记忆方法。这个可选的、固定次版本的依赖不会进入核心 SDK 和服务器。`MemoryManager` 可以独立于 agent 的会话数据库使用这个数据库。与记忆无关的功能会直接拒绝,而不是使用框架默认的存储。 + + + +## 不变量 + +每个适配器都绑定一个用户和一个应用存储。每次 SDK 调用都携带该用户和派生出的会话;键包含同一个作用域摘要以及原生 id 摘要。如果指定了不同的用户,则会被拒绝。原生用户记忆以 JSON 形式保存在 Loom 的情景行中,保留 id、元数据和修订版本,不会对不同的原生记录做语义合并。操作者和来源的出处信息来自 Loom 的常规写入路径。适用常规的记忆删除、擦除和滚动 schema 规则。 + +列表按照限定数量并经过投影的分页方式读取,对重叠部分去重,并在转换为原生对象之前补全被截断的值。内容、主题和归属过滤,以及排序、分页和统计,都在这个限定了用户和存储范围的快照上执行。没有本地持久状态。并发编辑时保留服务器最后一次写入;批量操作是一系列写入,失败时可能只完成一部分。需要隔离互不信任的应用时,请使用命名空间授权。 + + + +## 源码入口 + +- `sdk/python/loom/integrations/agno.py`:`LoomMemoryDb`。 +- `sdk/python/tests/test_agno.py`:原生记忆管理器的行为。 +- `tests/integration/test_sdk_agno_memory.py`:实际运行中的记忆作用域和出处信息。 diff --git a/i18n/zh-CN/docs/architecture/google-adk-adapter.md b/i18n/zh-CN/docs/architecture/google-adk-adapter.md new file mode 100644 index 0000000000..0346452741 --- /dev/null +++ b/i18n/zh-CN/docs/architecture/google-adk-adapter.md @@ -0,0 +1,26 @@ + +> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/google-adk-adapter.md)翻译,内容以英文原文为准。 +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/google-adk-adapter.md), which is authoritative. + + + +# Google ADK 记忆服务 + +Google ADK 适配器通过 Loom 的 Python 和 TypeScript SDK 实现该框架的记忆服务。框架包是可选依赖。每个应用都使用独立的 Loom 命名空间,因为其中的知识文档会与该命名空间的所有读取者共享。 + +会话写入会从处于活动状态的用户事件和模型事件中提取文本,排除工具负载和思考内容,然后分批调用 `memory.set_from_messages`,每批大小有上限。两个 SDK 在发起任何调用之前,都会拒绝空的、哨兵值的以及带有首尾空白的用户 id。每次调用都携带最终用户,以及由用户和原生会话 id 派生出的会话。Python 还实现了已安装框架中的增量事件、直接记忆和删除方法。Python 的删除 id 包含 key、会话、写入者和确切版本,并直接调用 `memory.delete_version`。版本不存在或已被改写时为空操作,且不会选中其他写入者的行。记忆搜索命中结果中新增的 `agent` 响应字段来自存储行的身份,包括被停放的页面。没有已知写入者或版本的命中结果没有删除 id。旧客户端会忽略这个额外字段;要进行精确的 ADK 删除,需要服务器提供该字段。这不会增加持久化列,也不需要迁移。TypeScript 返回按写入者限定范围的信息性 id;其已安装的框架接口没有删除方法。 + +搜索时,先为绑定的用户调用 `memory.search`,再用限定在命名空间内的 `knowledge.search` 的结果填充剩余的可用结果位置。知识是共享的应用上下文,而不是用户私有的记忆。两个 SDK 使用相同的摘要编码;框架原生的时间戳表示在边界处进行转换。一个服务实例只绑定一个应用。需要隔离互不信任的应用时,使用命名空间授权。 + + + +## 源码入口 + +- `sdk/python/loom/integrations/google_adk.py`:`LoomMemoryService`。 +- `sdk/typescript/src/integrations/google-adk.ts`:`LoomMemoryService`。 + + + +## 不变量 + +服务器通过其常规写入路径提供操作者和来源的出处信息。适配器不添加数据库、模式或提供方。现有的记忆删除、知识擦除和滚动升级规则同样适用。语义提取可能会修订事实;该服务不是精确的对话记录存储。知识结果没有用户记忆 id,无法通过记忆服务删除。 diff --git a/i18n/zh-CN/docs/architecture/haystack-adapter.md b/i18n/zh-CN/docs/architecture/haystack-adapter.md new file mode 100644 index 0000000000..4f2d5a6790 --- /dev/null +++ b/i18n/zh-CN/docs/architecture/haystack-adapter.md @@ -0,0 +1,27 @@ + +> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/haystack-adapter.md)翻译,内容以英文原文为准。 +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/haystack-adapter.md), which is authoritative. + + + +# Haystack 文档存储与检索器 + +可选的 Haystack 3.5 适配器通过同步的 Loom SDK 实现其文档存储协议和原生检索组件。核心 SDK 和服务器不依赖该框架。每次 HTTP 调用的客户端生命周期由 SDK 管理;适配器不会留下服务器、本地数据库、缓存或持久的后台进程。 + + + +## 不变量 + +存储会把每个原生文档 id 映射为位于存储专属前缀下的哈希来源 URI。匹配的标签用于限定列表和检索的范围。完整的原生文档序列化内容(包括元数据、嵌入向量和二进制字段)保存在文档的原始文件字节中。分块元数据只携带一个很小的格式标记;文本作为文档内容建立索引,没有文本时则索引 id。Loom 常规的文档写入、来源溯源、命名空间授权、版本控制和擦除路径适用于每一次写入和删除。文档在命名空间内共享,而不是用户私有。 + +计数和过滤会通过游标分页读取并还原整个存储。原生过滤辅助函数负责处理比较和布尔逻辑。检索最多搜索 100 个分块,并带有明确的命名空间、标签和 URI 边界,然后还原完整文档,按来源 URI 去重,同时保留每个文档排名最高的命中结果。这些操作没有跨请求的快照。并发写入时,Loom 可能返回冲突。重复检查和多文档操作不是事务。 + +序列化后的连接信息携带 Haystack 环境变量 Secret 引用;原始的 Secret 令牌会拒绝序列化。显式的端点 URL 不允许内嵌密钥。适配器保留 Haystack 的管道反序列化信任策略,从不注册受信任的模块,也不会选择不安全的反序列化。 + + + +## 源码入口 + +- `sdk/python/loom/integrations/haystack.py`:`LoomDocumentStore` 和 `LoomRetriever`。 +- `sdk/python/tests/test_haystack.py`:原生文档存储与管道行为。 +- `tests/integration/test_sdk_haystack.py`:实时文档持久化与检索。