--- layout: default title: "Referencia de la API de Python de TrustGraph" parent: "Spanish (Beta)" --- # Referencia de la API de Python de TrustGraph > **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta. ## Instalación ```bash pip install trustgraph ``` ## Inicio rápido Todas las clases y tipos se importan del paquete `trustgraph.api`: ```python from trustgraph.api import Api, Triple, ConfigKey # Create API client api = Api(url="http://localhost:8088/") # Get a flow instance flow = api.flow().id("default") # Execute a graph RAG query response = flow.graph_rag( query="What are the main topics?", user="trustgraph", collection="default" ) ``` ## Tabla de Contenidos ### Núcleo [Api](#api) ### Clientes de Flujo [Flow](#flow) [FlowInstance](#flowinstance) [AsyncFlow](#asyncflow) [AsyncFlowInstance](#asyncflowinstance) ### Clientes de WebSocket [SocketClient](#socketclient) [SocketFlowInstance](#socketflowinstance) [AsyncSocketClient](#asyncsocketclient) [AsyncSocketFlowInstance](#asyncsocketflowinstance) ### Operaciones Masivas [BulkClient](#bulkclient) [AsyncBulkClient](#asyncbulkclient) ### Métricas [Metrics](#metrics) [AsyncMetrics](#asyncmetrics) ### Tipos de Datos [Triple](#triple) [ConfigKey](#configkey) [ConfigValue](#configvalue) [DocumentMetadata](#documentmetadata) [ProcessingMetadata](#processingmetadata) [CollectionMetadata](#collectionmetadata) [StreamingChunk](#streamingchunk) [AgentThought](#agentthought) [AgentObservation](#agentobservation) [AgentAnswer](#agentanswer) [RAGChunk](#ragchunk) ### Excepciones [ProtocolException](#protocolexception) [TrustGraphException](#trustgraphexception) [AgentError](#agenterror) [ConfigError](#configerror) [DocumentRagError](#documentragerror) [FlowError](#flowerror) [GatewayError](#gatewayerror) [GraphRagError](#graphragerror) [LLMError](#llmerror) [LoadError](#loaderror) [LookupError](#lookuperror) [NLPQueryError](#nlpqueryerror) [RowsQueryError](#rowsqueryerror) [RequestError](#requesterror) [StructuredQueryError](#structuredqueryerror) [UnexpectedError](#unexpectederror) [ApplicationException](#applicationexception) -- ## `Api` ```python from trustgraph.api import Api ``` Cliente principal de la API TrustGraph para operaciones sincrónicas y asincrónicas. Esta clase proporciona acceso a todos los servicios de TrustGraph, incluyendo la gestión de flujos, operaciones de grafos de conocimiento, procesamiento de documentos, consultas RAG y más. Soporta tanto patrones de comunicación basados en REST como en WebSocket. El cliente se puede utilizar como un administrador de contexto para la limpieza automática de recursos: ```python with Api(url="http://localhost:8088/") as api: result = api.flow().id("default").graph_rag(query="test") ``` ### Métodos ### `__aenter__(self)` Ingrese al administrador de contexto asíncrono. ### `__aexit__(self, *args)` Salga del administrador de contexto asíncrono y cierre las conexiones. ### `__enter__(self)` Ingrese al administrador de contexto síncrono. ### `__exit__(self, *args)` Salga del administrador de contexto síncrono y cierre las conexiones. ### `__init__(self, url='http://localhost:8088/', timeout=60, token: str | None = None)` Inicialice el cliente de la API TrustGraph. **Argumentos:** `url`: URL base para la API TrustGraph (por defecto: "http://localhost:8088/"") `timeout`: Tiempo de espera de la solicitud en segundos (por defecto: 60) `token`: Token de portador opcional para la autenticación **Ejemplo:** ```python # Local development api = Api() # Production with authentication api = Api( url="https://trustgraph.example.com/", timeout=120, token="your-api-token" ) ``` ### `aclose(self)` Cerrar todas las conexiones de cliente asíncronas. Este método cierra las conexiones asíncronas de WebSocket, las operaciones masivas y los flujos. Se llama automáticamente al salir de un administrador de contexto asíncrono. **Ejemplo:** ```python api = Api() async_socket = api.async_socket() # ... use async_socket await api.aclose() # Clean up connections # Or use async context manager (automatic cleanup) async with Api() as api: async_socket = api.async_socket() # ... use async_socket # Automatically closed ``` ### `async_bulk(self)` Obtenga un cliente para operaciones masivas asíncronas. Proporciona operaciones de importación/exportación masivas en estilo async/await a través de WebSocket para un manejo eficiente de grandes conjuntos de datos. **Devuelve:** AsyncBulkClient: Cliente para operaciones masivas asíncronas. **Ejemplo:** ```python async_bulk = api.async_bulk() # Export triples asynchronously async for triple in async_bulk.export_triples(flow="default"): print(f"{triple.s} {triple.p} {triple.o}") # Import with async generator async def triple_gen(): yield Triple(s="subj", p="pred", o="obj") # ... more triples await async_bulk.import_triples( flow="default", triples=triple_gen() ) ``` ### `async_flow(self)` Obtenga un cliente de flujo basado en REST asíncrono. Proporciona acceso al estilo async/await a las operaciones de flujo. Esto es preferible para aplicaciones y marcos de trabajo de Python asíncronos (FastAPI, aiohttp, etc.). **Devuelve:** AsyncFlow: Cliente de flujo asíncrono **Ejemplo:** ```python async_flow = api.async_flow() # List flows flow_ids = await async_flow.list() # Execute operations instance = async_flow.id("default") result = await instance.text_completion( system="You are helpful", prompt="Hello" ) ``` ### `async_metrics(self)` Obtenga un cliente de métricas asíncrono. Proporciona acceso al estilo async/await a las métricas de Prometheus. **Retorna:** AsyncMetrics: Cliente de métricas asíncrono **Ejemplo:** ```python async_metrics = api.async_metrics() prometheus_text = await async_metrics.get() print(prometheus_text) ``` ### `async_socket(self)` Obtenga un cliente WebSocket asíncrono para operaciones de transmisión. Proporciona acceso a WebSocket con estilo async/await y soporte para transmisión. Este es el método preferido para la transmisión asíncrona en Python. **Retorna:** AsyncSocketClient: Cliente WebSocket asíncrono **Ejemplo:** ```python async_socket = api.async_socket() flow = async_socket.flow("default") # Stream agent responses async for chunk in flow.agent( question="Explain quantum computing", user="trustgraph", streaming=True ): if hasattr(chunk, 'content'): print(chunk.content, end='', flush=True) ``` ### `bulk(self)` Obtenga un cliente de operaciones masivas sincrónicas para la importación/exportación. Las operaciones masivas permiten la transferencia eficiente de grandes conjuntos de datos a través de conexiones WebSocket, incluyendo triples, incrustaciones, contextos de entidades y objetos. **Devuelve:** BulkClient: Cliente de operaciones masivas sincrónicas. **Ejemplo:** ```python bulk = api.bulk() # Export triples for triple in bulk.export_triples(flow="default"): print(f"{triple.s} {triple.p} {triple.o}") # Import triples def triple_generator(): yield Triple(s="subj", p="pred", o="obj") # ... more triples bulk.import_triples(flow="default", triples=triple_generator()) ``` ### `close(self)` Cerrar todas las conexiones de cliente sincrónicas. Este método cierra las conexiones de WebSocket y de operaciones masivas. Se llama automáticamente al salir de un administrador de contexto. **Ejemplo:** ```python api = Api() socket = api.socket() # ... use socket api.close() # Clean up connections # Or use context manager (automatic cleanup) with Api() as api: socket = api.socket() # ... use socket # Automatically closed ``` ### `collection(self)` Obtenga un cliente de Collection para administrar colecciones de datos. Las colecciones organizan documentos y datos de grafos de conocimiento en agrupaciones lógicas para el aislamiento y el control de acceso. **Devuelve:** Collection: Cliente de administración de colecciones **Ejemplo:** ```python collection = api.collection() # List collections colls = collection.list_collections(user="trustgraph") # Update collection metadata collection.update_collection( user="trustgraph", collection="default", name="Default Collection", description="Main data collection" ) ``` ### `config(self)` Obtenga un cliente de Config para administrar la configuración. **Retorna:** Config: Cliente de administración de configuración **Ejemplo:** ```python config = api.config() # Get configuration values values = config.get([ConfigKey(type="llm", key="model")]) # Set configuration config.put([ConfigValue(type="llm", key="model", value="gpt-4")]) ``` ### `flow(self)` Obtenga un cliente de Flow para administrar e interactuar con flujos. Los flujos son las unidades de ejecución principales en TrustGraph, y proporcionan acceso a servicios como agentes, consultas RAG, incrustaciones y procesamiento de documentos. **Devuelve:** Flow: Cliente de administración de flujos. **Ejemplo:** ```python flow_client = api.flow() # List available blueprints blueprints = flow_client.list_blueprints() # Get a specific flow instance flow_instance = flow_client.id("default") response = flow_instance.text_completion( system="You are helpful", prompt="Hello" ) ``` ### `knowledge(self)` Obtenga un cliente de Knowledge para administrar los núcleos de grafos de conocimiento. **Retorna:** Knowledge: Cliente de administración de grafos de conocimiento. **Ejemplo:** ```python knowledge = api.knowledge() # List available KG cores cores = knowledge.list_kg_cores(user="trustgraph") # Load a KG core knowledge.load_kg_core(id="core-123", user="trustgraph") ``` ### `library(self)` Obtenga un cliente de la biblioteca para la gestión de documentos. La biblioteca proporciona almacenamiento de documentos, gestión de metadatos y coordinación del flujo de trabajo de procesamiento. **Devuelve:** Biblioteca: Cliente de gestión de la biblioteca de documentos **Ejemplo:** ```python library = api.library() # Add a document library.add_document( document=b"Document content", id="doc-123", metadata=[], user="trustgraph", title="My Document", comments="Test document" ) # List documents docs = library.get_documents(user="trustgraph") ``` ### `metrics(self)` Obtiene un cliente de métricas sincrónico para la monitorización. Recupera métricas en formato Prometheus del servicio TrustGraph para la monitorización y la observabilidad. **Devuelve:** Métricas: Cliente de métricas sincrónico **Ejemplo:** ```python metrics = api.metrics() prometheus_text = metrics.get() print(prometheus_text) ``` ### `request(self, path, request)` Realizar una solicitud de API REST de bajo nivel. Este método se utiliza principalmente para uso interno, pero se puede utilizar para acceder directamente a la API cuando sea necesario. **Argumentos:** `path`: Ruta del punto final de la API (relativa a la URL base) `request`: Carga útil de la solicitud como un diccionario **Retorna:** dict: Objeto de respuesta **Lanza:** `ProtocolException`: Si el estado de la respuesta no es 200 o la respuesta no es JSON `ApplicationException`: Si la respuesta contiene un error **Ejemplo:** ```python response = api.request("flow", { "operation": "list-flows" }) ``` ### `socket(self)` Obtenga un cliente WebSocket síncrono para operaciones de transmisión. Las conexiones WebSocket proporcionan soporte de transmisión para respuestas en tiempo real de agentes, consultas RAG y finalizaciones de texto. Este método devuelve un envoltorio síncrono alrededor del protocolo WebSocket. **Retorna:** SocketClient: Cliente WebSocket síncrono **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") # Stream agent responses for chunk in flow.agent( question="Explain quantum computing", user="trustgraph", streaming=True ): if hasattr(chunk, 'content'): print(chunk.content, end='', flush=True) ``` -- ## `Flow` ```python from trustgraph.api import Flow ``` Cliente de gestión de flujo para operaciones de planos de flujo y instancias de flujo. Esta clase proporciona métodos para administrar planos de flujo (plantillas) y instancias de flujo (flujos en ejecución). Los planos definen la estructura y los parámetros de los flujos, mientras que las instancias representan flujos activos que pueden ejecutar servicios. ### Métodos ### `__init__(self, api)` Inicializar el cliente de flujo. **Argumentos:** `api`: Instancia de Api principal para realizar solicitudes. ### `delete_blueprint(self, blueprint_name)` Eliminar un plano de flujo. **Argumentos:** `blueprint_name`: Nombre del plano a eliminar. **Ejemplo:** ```python api.flow().delete_blueprint("old-blueprint") ``` ### `get(self, id)` Obtener la definición de una instancia de flujo en ejecución. **Argumentos:** `id`: ID de la instancia de flujo **Retorna:** dict: Definición de la instancia de flujo **Ejemplo:** ```python flow_def = api.flow().get("default") print(flow_def) ``` ### `get_blueprint(self, blueprint_name)` Obtener una definición de diagrama de flujo por nombre. **Argumentos:** `blueprint_name`: Nombre del diagrama de flujo a recuperar **Retorna:** dict: Definición del diagrama de flujo como un diccionario **Ejemplo:** ```python blueprint = api.flow().get_blueprint("default") print(blueprint) # Blueprint configuration ``` ### `id(self, id='default')` Obtener una instancia de FlowInstance para ejecutar operaciones en un flujo específico. **Argumentos:** `id`: Identificador del flujo (predeterminado: "default") **Retorna:** FlowInstance: Instancia de flujo para operaciones de servicio **Ejemplo:** ```python flow = api.flow().id("my-flow") response = flow.text_completion( system="You are helpful", prompt="Hello" ) ``` ### `list(self)` Listar todas las instancias de flujo activas. **Retorna:** list[str]: Lista de identificadores de instancias de flujo. **Ejemplo:** ```python flows = api.flow().list() print(flows) # ['default', 'flow-1', 'flow-2', ...] ``` ### `list_blueprints(self)` Listar todos los planos de flujo disponibles. **Retorna:** list[str]: Lista de nombres de planos. **Ejemplo:** ```python blueprints = api.flow().list_blueprints() print(blueprints) # ['default', 'custom-flow', ...] ``` ### `put_blueprint(self, blueprint_name, definition)` Crear o actualizar un esquema de flujo. **Argumentos:** `blueprint_name`: Nombre para el esquema. `definition`: Diccionario de definición del esquema. **Ejemplo:** ```python definition = { "services": ["text-completion", "graph-rag"], "parameters": {"model": "gpt-4"} } api.flow().put_blueprint("my-blueprint", definition) ``` ### `request(self, path=None, request=None)` Realizar una solicitud de API con ámbito de flujo. **Argumentos:** `path`: Sufijo de ruta opcional para los puntos finales de flujo. `request`: Diccionario de carga útil de la solicitud. **Retorna:** dict: Objeto de respuesta. **Genera:** `RuntimeError`: Si no se especifica el parámetro de solicitud. ### `start(self, blueprint_name, id, description, parameters=None)` Iniciar una nueva instancia de flujo a partir de un plano. **Argumentos:** `blueprint_name`: Nombre del plano a instanciar. `id`: Identificador único para la instancia de flujo. `description`: Descripción legible por humanos. `parameters`: Diccionario de parámetros opcionales. **Ejemplo:** ```python api.flow().start( blueprint_name="default", id="my-flow", description="My custom flow", parameters={"model": "gpt-4"} ) ``` ### `stop(self, id)` Detener una instancia de flujo en ejecución. **Argumentos:** `id`: ID de la instancia de flujo a detener. **Ejemplo:** ```python api.flow().stop("my-flow") ``` -- ## `FlowInstance` ```python from trustgraph.api import FlowInstance ``` Cliente de instancia de flujo para ejecutar servicios en un flujo específico. Esta clase proporciona acceso a todos los servicios de TrustGraph, incluyendo: Completado de texto y embeddings Operaciones de agentes con gestión de estado Consultas RAG de gráficos y documentos Operaciones de grafos de conocimiento (triples, objetos) Carga y procesamiento de documentos Conversión de lenguaje natural a consulta GraphQL Análisis de datos estructurados y detección de esquemas Ejecución de herramientas MCP Plantillas de prompts Los servicios se acceden a través de una instancia de flujo en ejecución identificada por ID. ### Métodos ### `__init__(self, api, id)` Inicializar FlowInstance. **Argumentos:** `api`: Cliente de flujo padre `id`: Identificador de la instancia de flujo ### `agent(self, question, user='trustgraph', state=None, group=None, history=None)` Ejecutar una operación de agente con capacidades de razonamiento y uso de herramientas. Los agentes pueden realizar razonamiento en múltiples pasos, usar herramientas y mantener el estado de la conversación en las interacciones. Esta es una versión síncrona no basada en streaming. **Argumentos:** `question`: Pregunta o instrucción del usuario `user`: Identificador del usuario (por defecto: "trustgraph") `state`: Diccionario de estado opcional para conversaciones con estado `group`: Identificador de grupo opcional para contextos multiusuario `history`: Historial de conversación opcional como lista de diccionarios de mensajes **Retorna:** str: Respuesta final del agente **Ejemplo:** ```python flow = api.flow().id("default") # Simple question answer = flow.agent( question="What is the capital of France?", user="trustgraph" ) # With conversation history history = [ {"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Hi! How can I help?"} ] answer = flow.agent( question="Tell me about Paris", user="trustgraph", history=history ) ``` ### `detect_type(self, sample)` Detectar el tipo de datos de una muestra de datos estructurados. **Argumentos:** `sample`: Muestra de datos a analizar (contenido de cadena) **Retorna:** diccionario con detected_type, confidence y metadatos opcionales. ### `diagnose_data(self, sample, schema_name=None, options=None)` Realizar un diagnóstico de datos combinado: detectar el tipo y generar un descriptor. **Argumentos:** `sample`: Muestra de datos a analizar (contenido de cadena) `schema_name`: Nombre de esquema de destino opcional para la generación del descriptor. `options`: Parámetros opcionales (por ejemplo, delimitador para CSV). **Retorna:** diccionario con detected_type, confidence, descriptor y metadatos. ### `document_embeddings_query(self, text, user, collection, limit=10)` Consultar fragmentos de documentos utilizando similitud semántica. Encuentra fragmentos de documentos cuyo contenido sea semánticamente similar al texto de entrada, utilizando incrustaciones vectoriales. **Argumentos:** `text`: Texto de consulta para la búsqueda semántica. `user`: Identificador de usuario/espacio de claves. `collection`: Identificador de colección. `limit`: Número máximo de resultados (por defecto: 10). **Retorna:** diccionario: Resultados de la consulta con fragmentos que contienen chunk_id y score. **Ejemplo:** ```python flow = api.flow().id("default") results = flow.document_embeddings_query( text="machine learning algorithms", user="trustgraph", collection="research-papers", limit=5 ) # results contains {"chunks": [{"chunk_id": "doc1/p0/c0", "score": 0.95}, ...]} ``` ### `document_rag(self, query, user='trustgraph', collection='default', doc_limit=10)` Ejecutar una consulta de Generación Aumentada por Recuperación (RAG) basada en documentos. RAG basada en documentos utiliza incrustaciones vectoriales para encontrar fragmentos de documentos relevantes, y luego genera una respuesta utilizando un LLM con esos fragmentos como contexto. **Argumentos:** `query`: Consulta en lenguaje natural `user`: Identificador de usuario/espacio de claves (por defecto: "trustgraph") `collection`: Identificador de colección (por defecto: "default") `doc_limit`: Número máximo de fragmentos de documentos a recuperar (por defecto: 10) **Retorna:** str: Respuesta generada que incorpora el contexto del documento **Ejemplo:** ```python flow = api.flow().id("default") response = flow.document_rag( query="Summarize the key findings", user="trustgraph", collection="research-papers", doc_limit=5 ) print(response) ``` ### `embeddings(self, texts)` Genera incrustaciones vectoriales para uno o más textos. Convierte textos en representaciones vectoriales densas adecuadas para la búsqueda semántica y la comparación de similitud. **Argumentos:** `texts`: Lista de textos de entrada para incrustar **Retorna:** list[list[list[float]]]: Incrustaciones vectoriales, un conjunto por texto de entrada **Ejemplo:** ```python flow = api.flow().id("default") vectors = flow.embeddings(["quantum computing"]) print(f"Embedding dimension: {len(vectors[0][0])}") ``` ### `generate_descriptor(self, sample, data_type, schema_name, options=None)` Generar un descriptor para el mapeo de datos estructurados a un esquema específico. **Argumentos:** `sample`: Muestra de datos a analizar (contenido de cadena) `data_type`: Tipo de datos (csv, json, xml) `schema_name`: Nombre del esquema de destino para la generación del descriptor `options`: Parámetros opcionales (por ejemplo, delimitador para CSV) **Retorna:** diccionario con el descriptor y metadatos ### `graph_embeddings_query(self, text, user, collection, limit=10)` Consultar entidades de un grafo de conocimiento utilizando similitud semántica. Encuentra entidades en el grafo de conocimiento cuyas descripciones son semánticamente similares al texto de entrada, utilizando incrustaciones vectoriales. **Argumentos:** `text`: Texto de consulta para la búsqueda semántica `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección `limit`: Número máximo de resultados (por defecto: 10) **Retorna:** diccionario: Resultados de la consulta con entidades similares **Ejemplo:** ```python flow = api.flow().id("default") results = flow.graph_embeddings_query( text="physicist who discovered radioactivity", user="trustgraph", collection="scientists", limit=5 ) # results contains {"entities": [{"entity": {...}, "score": 0.95}, ...]} ``` ### `graph_rag(self, query, user='trustgraph', collection='default', entity_limit=50, triple_limit=30, max_subgraph_size=150, max_path_length=2)` Ejecutar una consulta de Generación Aumentada por Recuperación (RAG) basada en grafos. Graph RAG utiliza la estructura del grafo de conocimiento para encontrar el contexto relevante mediante el recorrido de las relaciones entre entidades, y luego genera una respuesta utilizando un LLM. **Argumentos:** `query`: Consulta en lenguaje natural `user`: Identificador de usuario/espacio de claves (por defecto: "trustgraph") `collection`: Identificador de colección (por defecto: "default") `entity_limit`: Número máximo de entidades a recuperar (por defecto: 50) `triple_limit`: Número máximo de triples por entidad (por defecto: 30) `max_subgraph_size`: Número máximo total de triples en el subgrafo (por defecto: 150) `max_path_length`: Profundidad máxima de recorrido (por defecto: 2) **Retorna:** str: Respuesta generada que incorpora el contexto del grafo **Ejemplo:** ```python flow = api.flow().id("default") response = flow.graph_rag( query="Tell me about Marie Curie's discoveries", user="trustgraph", collection="scientists", entity_limit=20, max_path_length=3 ) print(response) ``` ### `load_document(self, document, id=None, metadata=None, user=None, collection=None)` Cargar un documento binario para su procesamiento. Sube un documento (PDF, DOCX, imágenes, etc.) para la extracción y procesamiento a través de la canalización de documentos del flujo. **Argumentos:** `document`: Contenido del documento como bytes `id`: Identificador de documento opcional (se genera automáticamente si es None) `metadata`: Metadatos opcionales (lista de Triples o objeto con método emit) `user`: Identificador de usuario/espacio de claves (opcional) `collection`: Identificador de colección (opcional) **Retorna:** dict: Respuesta de procesamiento **Lanza:** `RuntimeError`: Si se proporcionan metadatos sin id **Ejemplo:** ```python flow = api.flow().id("default") # Load a PDF document with open("research.pdf", "rb") as f: result = flow.load_document( document=f.read(), id="research-001", user="trustgraph", collection="papers" ) ``` ### `load_text(self, text, id=None, metadata=None, charset='utf-8', user=None, collection=None)` Cargar contenido de texto para su procesamiento. Carga contenido de texto para la extracción y el procesamiento a través de la canalización de texto del flujo. **Argumentos:** `text`: Contenido de texto como bytes `id`: Identificador de documento opcional (se genera automáticamente si es None) `metadata`: Metadatos opcionales (lista de Triples o objeto con método emit) `charset`: Codificación de caracteres (predeterminado: "utf-8") `user`: Identificador de usuario/espacio de claves (opcional) `collection`: Identificador de colección (opcional) **Retorna:** dict: Respuesta de procesamiento **Genera:** `RuntimeError`: Si se proporcionan metadatos sin id **Ejemplo:** ```python flow = api.flow().id("default") # Load text content text_content = b"This is the document content..." result = flow.load_text( text=text_content, id="text-001", charset="utf-8", user="trustgraph", collection="documents" ) ``` ### `mcp_tool(self, name, parameters={})` Ejecutar una herramienta de Protocolo de Contexto de Modelo (MCP). Las herramientas MCP proporcionan funcionalidades extensibles para agentes y flujos de trabajo, permitiendo la integración con sistemas y servicios externos. **Argumentos:** `name`: Nombre/identificador de la herramienta `parameters`: Diccionario de parámetros de la herramienta (por defecto: {}) **Retorna:** str o dict: Resultado de la ejecución de la herramienta **Genera:** `ProtocolException`: Si el formato de la respuesta no es válido **Ejemplo:** ```python flow = api.flow().id("default") # Execute a tool result = flow.mcp_tool( name="search-web", parameters={"query": "latest AI news", "limit": 5} ) ``` ### `nlp_query(self, question, max_results=100)` Convertir una pregunta en lenguaje natural en una consulta GraphQL. **Argumentos:** `question`: Pregunta en lenguaje natural `max_results`: Número máximo de resultados a devolver (por defecto: 100) **Retorna:** diccionario con graphql_query, variables, detected_schemas, confidence ### `prompt(self, id, variables)` Ejecutar una plantilla de prompt con sustitución de variables. Las plantillas de solicitud permiten patrones de solicitud reutilizables con variables dinámicas. de sustitución, útiles para una ingeniería de solicitudes consistente. **Argumentos:** `id`: Identificador de la plantilla de solicitud. `variables`: Diccionario de mapeos de nombres de variables a valores. **Retorna:** str o dict: Resultado de la solicitud renderizada (texto u objeto estructurado). **Genera:** `ProtocolException`: Si el formato de la respuesta no es válido. **Ejemplo:** ```python flow = api.flow().id("default") # Text template result = flow.prompt( id="summarize-template", variables={"topic": "quantum computing", "length": "brief"} ) # Structured template result = flow.prompt( id="extract-entities", variables={"text": "Marie Curie won Nobel Prizes"} ) ``` ### `request(self, path, request)` Realice una solicitud de servicio en esta instancia de flujo. **Argumentos:** `path`: Ruta del servicio (por ejemplo, "service/text-completion") `request`: Diccionario de carga útil de la solicitud **Retorna:** dict: Respuesta del servicio ### `row_embeddings_query(self, text, schema_name, user='trustgraph', collection='default', index_name=None, limit=10)` Consulta datos de fila utilizando similitud semántica en campos indexados. Encuentra filas cuyos valores de campo indexados son semánticamente similares al texto de entrada, utilizando incrustaciones vectoriales. Esto permite la coincidencia difusa/semántica en datos estructurados. **Argumentos:** `text`: Texto de consulta para la búsqueda semántica `schema_name`: Nombre del esquema para buscar `user`: Identificador de usuario/espacio de claves (predeterminado: "trustgraph") `collection`: Identificador de colección (predeterminado: "default") `index_name`: Nombre de índice opcional para filtrar la búsqueda a un índice específico `limit`: Número máximo de resultados (predeterminado: 10) **Retorna:** dict: Resultados de la consulta con coincidencias que contienen index_name, index_value, text y score **Ejemplo:** ```python flow = api.flow().id("default") # Search for customers by name similarity results = flow.row_embeddings_query( text="John Smith", schema_name="customers", user="trustgraph", collection="sales", limit=5 ) # Filter to specific index results = flow.row_embeddings_query( text="machine learning engineer", schema_name="employees", index_name="job_title", limit=10 ) ``` ### `rows_query(self, query, user='trustgraph', collection='default', variables=None, operation_name=None)` Ejecutar una consulta GraphQL contra filas estructuradas en el grafo de conocimiento. Consulta datos estructurados utilizando la sintaxis GraphQL, lo que permite consultas complejas con filtrado, agregación y recorrido de relaciones. **Argumentos:** `query`: Cadena de consulta GraphQL `user`: Identificador de usuario/espacio de claves (por defecto: "trustgraph") `collection`: Identificador de colección (por defecto: "default") `variables`: Diccionario opcional de variables de consulta `operation_name`: Nombre de operación opcional para documentos de múltiples operaciones **Retorna:** dict: Respuesta GraphQL con los campos 'data', 'errors' y/o 'extensions' **Genera:** `ProtocolException`: Si ocurre un error a nivel del sistema **Ejemplo:** ```python flow = api.flow().id("default") # Simple query query = ''' { scientists(limit: 10) { name field discoveries } } ''' result = flow.rows_query( query=query, user="trustgraph", collection="scientists" ) # Query with variables query = ''' query GetScientist($name: String!) { scientists(name: $name) { name nobelPrizes } } ''' result = flow.rows_query( query=query, variables={"name": "Marie Curie"} ) ``` ### `schema_selection(self, sample, options=None)` Seleccionar esquemas coincidentes para una muestra de datos utilizando análisis de consultas. **Argumentos:** `sample`: Muestra de datos a analizar (contenido de cadena) `options`: Parámetros opcionales **Retorna:** diccionario con el array schema_matches y metadatos ### `structured_query(self, question, user='trustgraph', collection='default')` Ejecutar una pregunta en lenguaje natural contra datos estructurados. Combina la conversión de consultas NLP y la ejecución de GraphQL. **Argumentos:** `question`: Pregunta en lenguaje natural `user`: Identificador de keyspace de Cassandra (por defecto: "trustgraph") `collection`: Identificador de colección de datos (por defecto: "default") **Retorna:** diccionario con datos y posibles errores ### `text_completion(self, system, prompt)` Ejecutar la finalización de texto utilizando el LLM del flujo. **Argumentos:** `system`: Prompt del sistema que define el comportamiento del asistente `prompt`: Prompt/pregunta del usuario **Retorna:** str: Texto de respuesta generado **Ejemplo:** ```python flow = api.flow().id("default") response = flow.text_completion( system="You are a helpful assistant", prompt="What is quantum computing?" ) print(response) ``` ### `triples_query(self, s=None, p=None, o=None, user=None, collection=None, limit=10000)` Consultar tripletas del grafo de conocimiento utilizando la coincidencia de patrones. Busca tripletas RDF que coincidan con los patrones de sujeto, predicado y/o objeto dados. Los parámetros no especificados actúan como comodines. **Argumentos:** `s`: URI del sujeto (opcional, usar None para comodín) `p`: URI del predicado (opcional, usar None para comodín) `o`: URI del objeto o Literal (opcional, usar None para comodín) `user`: Identificador de usuario/espacio de claves (opcional) `collection`: Identificador de colección (opcional) `limit`: Número máximo de resultados a devolver (por defecto: 10000) **Devuelve:** list[Triple]: Lista de objetos Triple coincidentes **Genera:** `RuntimeError`: Si s o p no son un Uri, o o no es un Uri/Literal **Ejemplo:** ```python from trustgraph.knowledge import Uri, Literal flow = api.flow().id("default") # Find all triples about a specific subject triples = flow.triples_query( s=Uri("http://example.org/person/marie-curie"), user="trustgraph", collection="scientists" ) # Find all instances of a specific relationship triples = flow.triples_query( p=Uri("http://example.org/ontology/discovered"), limit=100 ) ``` -- ## `AsyncFlow` ```python from trustgraph.api import AsyncFlow ``` Cliente de gestión de flujos asíncronos que utiliza la API REST. Proporciona operaciones de gestión de flujos basadas en async/await, incluyendo listar, iniciar, detener flujos y gestionar definiciones de clases de flujos. También proporciona acceso a servicios específicos del flujo, como agentes, RAG y consultas, a través de puntos finales REST no basados en transmisión. Nota: Para el soporte de transmisión, utilice AsyncSocketClient en su lugar. ### Métodos ### `__init__(self, url: str, timeout: int, token: str | None) -> None` Inicializa el cliente de flujo asíncrono. **Argumentos:** `url`: URL base para la API de TrustGraph `timeout`: Tiempo de espera de la solicitud en segundos `token`: Token de portador opcional para la autenticación ### `aclose(self) -> None` Cierra el cliente asíncrono y libera recursos. Nota: La limpieza se gestiona automáticamente por los administradores de contexto de sesión de aiohttp. Este método se proporciona para mantener la coherencia con otros clientes asíncronos. ### `delete_class(self, class_name: str)` Elimina una definición de clase de flujo. Elimina una plantilla de clase de flujo del sistema. No afecta a instancias de flujo en ejecución. **Argumentos:** `class_name`: Nombre de la clase de flujo a eliminar **Ejemplo:** ```python async_flow = await api.async_flow() # Delete a flow class await async_flow.delete_class("old-flow-class") ``` ### `get(self, id: str) -> Dict[str, Any]` Obtener la definición del flujo. Recupera la configuración completa del flujo, incluyendo su nombre de clase, descripción y parámetros. **Argumentos:** `id`: Identificador del flujo **Retorna:** dict: Objeto de definición del flujo **Ejemplo:** ```python async_flow = await api.async_flow() # Get flow definition flow_def = await async_flow.get("default") print(f"Flow class: {flow_def.get('class-name')}") print(f"Description: {flow_def.get('description')}") ``` ### `get_class(self, class_name: str) -> Dict[str, Any]` Obtener la definición de la clase de flujo. Recupera la definición del esquema para una clase de flujo, incluyendo su esquema de configuración y enlaces de servicio. **Argumentos:** `class_name`: Nombre de la clase de flujo **Retorna:** dict: Objeto de definición de la clase de flujo **Ejemplo:** ```python async_flow = await api.async_flow() # Get flow class definition class_def = await async_flow.get_class("default") print(f"Services: {class_def.get('services')}") ``` ### `id(self, flow_id: str)` Obtener una instancia de cliente de flujo asíncrono. Devuelve un cliente para interactuar con los servicios de un flujo específico (agente, RAG, consultas, incrustaciones, etc.). **Argumentos:** `flow_id`: Identificador del flujo **Devuelve:** AsyncFlowInstance: Cliente para operaciones específicas del flujo **Ejemplo:** ```python async_flow = await api.async_flow() # Get flow instance flow = async_flow.id("default") # Use flow services result = await flow.graph_rag( query="What is TrustGraph?", user="trustgraph", collection="default" ) ``` ### `list(self) -> List[str]` Listar todos los identificadores de flujo. Recupera los ID de todos los flujos actualmente implementados en el sistema. **Retorna:** list[str]: Lista de identificadores de flujo. **Ejemplo:** ```python async_flow = await api.async_flow() # List all flows flows = await async_flow.list() print(f"Available flows: {flows}") ``` ### `list_classes(self) -> List[str]` Listar todos los nombres de las clases de flujo. Recupera los nombres de todas las clases de flujo (plantillas) disponibles en el sistema. **Retorna:** list[str]: Lista de nombres de clases de flujo. **Ejemplo:** ```python async_flow = await api.async_flow() # List available flow classes classes = await async_flow.list_classes() print(f"Available flow classes: {classes}") ``` ### `put_class(self, class_name: str, definition: Dict[str, Any])` Crear o actualizar una definición de clase de flujo. Almacena un esquema de clase de flujo que se puede utilizar para instanciar flujos. **Argumentos:** `class_name`: Nombre de la clase de flujo `definition`: Objeto de definición de la clase de flujo **Ejemplo:** ```python async_flow = await api.async_flow() # Create a custom flow class class_def = { "services": { "agent": {"module": "agent", "config": {...}}, "graph-rag": {"module": "graph-rag", "config": {...}} } } await async_flow.put_class("custom-flow", class_def) ``` ### `request(self, path: str, request_data: Dict[str, Any]) -> Dict[str, Any]` Realizar una solicitud HTTP POST asíncrona a la API de Gateway. Método interno para realizar solicitudes autenticadas a la API de TrustGraph. **Argumentos:** `path`: Ruta de punto final de la API (relativa a la URL base) `request_data`: Diccionario de carga útil de la solicitud **Retorna:** dict: Objeto de respuesta de la API **Genera:** `ProtocolException`: Si el estado HTTP no es 200 o la respuesta no es un JSON válido `ApplicationException`: Si la API devuelve una respuesta de error ### `start(self, class_name: str, id: str, description: str, parameters: Dict | None = None)` Inicia una nueva instancia de flujo. Crea e inicia un flujo a partir de una definición de clase de flujo con los parámetros especificados. **Argumentos:** `class_name`: Nombre de la clase de flujo a instanciar `id`: Identificador para la nueva instancia de flujo `description`: Descripción legible por humanos del flujo `parameters`: Parámetros de configuración opcionales para el flujo **Ejemplo:** ```python async_flow = await api.async_flow() # Start a flow from a class await async_flow.start( class_name="default", id="my-flow", description="Custom flow instance", parameters={"model": "claude-3-opus"} ) ``` ### `stop(self, id: str)` Detener un flujo en ejecución. Detiene y elimina una instancia de flujo, liberando sus recursos. **Argumentos:** `id`: Identificador del flujo a detener **Ejemplo:** ```python async_flow = await api.async_flow() # Stop a flow await async_flow.stop("my-flow") ``` -- ## `AsyncFlowInstance` ```python from trustgraph.api import AsyncFlowInstance ``` Cliente de instancia de flujo asíncrono. Proporciona acceso async/await a servicios con ámbito de flujo, incluyendo agentes, consultas RAG, incrustaciones y consultas de grafos. Todas las operaciones devuelven respuestas completas (no en streaming). Nota: Para soporte de streaming, utilice AsyncSocketFlowInstance en su lugar. ### Métodos ### `__init__(self, flow: trustgraph.api.async_flow.AsyncFlow, flow_id: str)` Inicializa una instancia de flujo asíncrono. **Argumentos:** `flow`: Cliente AsyncFlow padre `flow_id`: Identificador de flujo ### `agent(self, question: str, user: str, state: Dict | None = None, group: str | None = None, history: List | None = None, **kwargs: Any) -> Dict[str, Any]` Ejecuta una operación de agente (no en streaming). Ejecuta un agente para responder a una pregunta, con un estado de conversación opcional y historial. Devuelve la respuesta completa después de que el agente haya terminado de procesar. Nota: Este método no admite streaming. Para los pensamientos y observaciones del agente en tiempo real, utilice AsyncSocketFlowInstance.agent() en su lugar. **Argumentos:** `question`: Pregunta o instrucción del usuario `user`: Identificador del usuario `state`: Diccionario de estado opcional para el contexto de la conversación `group`: Identificador de grupo opcional para la gestión de sesiones `history`: Lista de historial de conversación opcional `**kwargs`: Parámetros adicionales específicos del servicio **Devuelve:** dict: Respuesta completa del agente, incluyendo la respuesta y los metadatos **Ejemplo:** ```python async_flow = await api.async_flow() flow = async_flow.id("default") # Execute agent result = await flow.agent( question="What is the capital of France?", user="trustgraph" ) print(f"Answer: {result.get('response')}") ``` ### `document_rag(self, query: str, user: str, collection: str, doc_limit: int = 10, **kwargs: Any) -> str` Ejecutar consulta RAG basada en documentos (no en streaming). Realiza Generación Aumentada por Recuperación utilizando incrustaciones de documentos. Recupera fragmentos de documentos relevantes mediante búsqueda semántica y luego genera una respuesta basada en los documentos recuperados. Devuelve la respuesta completa. Nota: Este método no admite el streaming. Para respuestas RAG en streaming, utilice AsyncSocketFlowInstance.document_rag() en su lugar. **Argumentos:** `query`: Texto de la consulta del usuario `user`: Identificador del usuario `collection`: Identificador de la colección que contiene los documentos `doc_limit`: Número máximo de fragmentos de documentos a recuperar (por defecto: 10) `**kwargs`: Parámetros adicionales específicos del servicio **Devuelve:** str: Respuesta generada completa basada en los datos del documento **Ejemplo:** ```python async_flow = await api.async_flow() flow = async_flow.id("default") # Query documents response = await flow.document_rag( query="What does the documentation say about authentication?", user="trustgraph", collection="docs", doc_limit=5 ) print(response) ``` ### `embeddings(self, texts: list, **kwargs: Any)` Generar incrustaciones (embeddings) para textos de entrada. Convierte textos en representaciones vectoriales numéricas utilizando el modelo de incrustación configurado en el flujo. Útil para la búsqueda semántica y comparaciones de similitud. **Argumentos:** `texts`: Lista de textos de entrada para incrustar `**kwargs`: Parámetros adicionales específicos del servicio **Retorna:** dict: Respuesta que contiene vectores de incrustación **Ejemplo:** ```python async_flow = await api.async_flow() flow = async_flow.id("default") # Generate embeddings result = await flow.embeddings(texts=["Sample text to embed"]) vectors = result.get("vectors") print(f"Embedding dimension: {len(vectors[0][0])}") ``` ### `graph_embeddings_query(self, text: str, user: str, collection: str, limit: int = 10, **kwargs: Any)` Consulta incrustaciones de grafos para la búsqueda semántica de entidades. Realiza una búsqueda semántica sobre las incrustaciones de entidades de grafos para encontrar entidades más relevantes para el texto de entrada. Devuelve entidades clasificadas por similitud. **Argumentos:** `text`: Texto de consulta para la búsqueda semántica `user`: Identificador de usuario `collection`: Identificador de la colección que contiene las incrustaciones de grafos `limit`: Número máximo de resultados a devolver (por defecto: 10) `**kwargs`: Parámetros adicionales específicos del servicio **Devuelve:** dict: Respuesta que contiene coincidencias de entidades clasificadas con puntuaciones de similitud **Ejemplo:** ```python async_flow = await api.async_flow() flow = async_flow.id("default") # Find related entities results = await flow.graph_embeddings_query( text="machine learning algorithms", user="trustgraph", collection="tech-kb", limit=5 ) for entity in results.get("entities", []): print(f"{entity['name']}: {entity['score']}") ``` ### `graph_rag(self, query: str, user: str, collection: str, max_subgraph_size: int = 1000, max_subgraph_count: int = 5, max_entity_distance: int = 3, **kwargs: Any) -> str` Ejecutar consulta RAG basada en grafos (no en streaming). Realiza la generación aumentada con recuperación utilizando datos de grafos de conocimiento. Identifica entidades relevantes y sus relaciones, y luego genera una respuesta basada en la estructura del grafo. Devuelve la respuesta completa. Nota: Este método no admite el streaming. Para respuestas RAG en streaming, utilice AsyncSocketFlowInstance.graph_rag() en su lugar. **Argumentos:** `query`: Texto de la consulta del usuario `user`: Identificador del usuario `collection`: Identificador de la colección que contiene el grafo de conocimiento `max_subgraph_size`: Número máximo de triples por subgrafo (por defecto: 1000) `max_subgraph_count`: Número máximo de subgrafos a recuperar (por defecto: 5) `max_entity_distance`: Distancia máxima del grafo para la expansión de entidades (por defecto: 3) `**kwargs`: Parámetros adicionales específicos del servicio **Devuelve:** str: Respuesta completa generada basada en datos del grafo **Ejemplo:** ```python async_flow = await api.async_flow() flow = async_flow.id("default") # Query knowledge graph response = await flow.graph_rag( query="What are the relationships between these entities?", user="trustgraph", collection="medical-kb", max_subgraph_count=3 ) print(response) ``` ### `request(self, service: str, request_data: Dict[str, Any]) -> Dict[str, Any]` Realizar una solicitud a un servicio con ámbito de flujo. Método interno para llamar a servicios dentro de esta instancia de flujo. **Argumentos:** `service`: Nombre del servicio (por ejemplo, "agent", "graph-rag", "triples") `request_data`: Carga útil de la solicitud al servicio **Retorna:** dict: Objeto de respuesta del servicio **Lanza:** `ProtocolException`: Si la solicitud falla o la respuesta es inválida `ApplicationException`: Si el servicio devuelve un error ### `row_embeddings_query(self, text: str, schema_name: str, user: str = 'trustgraph', collection: str = 'default', index_name: str | None = None, limit: int = 10, **kwargs: Any)` Consultar incrustaciones de filas para la búsqueda semántica en datos estructurados. Realiza una búsqueda semántica sobre las incrustaciones del índice de filas para encontrar filas cuyas valores de campo indexados sean más similares al texto de entrada. Permite la coincidencia difusa/semántica en datos estructurados. **Argumentos:** `text`: Texto de consulta para la búsqueda semántica `schema_name`: Nombre del esquema para buscar `user`: Identificador de usuario (por defecto: "trustgraph") `collection`: Identificador de colección (por defecto: "default") `index_name`: Nombre de índice opcional para filtrar la búsqueda a un índice específico `limit`: Número máximo de resultados a devolver (por defecto: 10) `**kwargs`: Parámetros adicionales específicos del servicio **Retorna:** dict: Respuesta que contiene coincidencias con index_name, index_value, text y score **Ejemplo:** ```python async_flow = await api.async_flow() flow = async_flow.id("default") # Search for customers by name similarity results = await flow.row_embeddings_query( text="John Smith", schema_name="customers", user="trustgraph", collection="sales", limit=5 ) for match in results.get("matches", []): print(f"{match['index_name']}: {match['index_value']} (score: {match['score']})") ``` ### `rows_query(self, query: str, user: str, collection: str, variables: Dict | None = None, operation_name: str | None = None, **kwargs: Any)` Ejecutar una consulta GraphQL en filas almacenadas. Consulta filas de datos estructurados utilizando la sintaxis GraphQL. Soporta consultas complejas con variables y operaciones con nombre. **Argumentos:** `query`: Cadena de consulta GraphQL `user`: Identificador de usuario `collection`: Identificador de la colección que contiene las filas `variables`: Variables de consulta GraphQL opcionales `operation_name`: Nombre de operación opcional para consultas con múltiples operaciones `**kwargs`: Parámetros adicionales específicos del servicio **Retorna:** dict: Respuesta GraphQL con datos y/o errores **Ejemplo:** ```python async_flow = await api.async_flow() flow = async_flow.id("default") # Execute GraphQL query query = ''' query GetUsers($status: String!) { users(status: $status) { id name email } } ''' result = await flow.rows_query( query=query, user="trustgraph", collection="users", variables={"status": "active"} ) for user in result.get("data", {}).get("users", []): print(f"{user['name']}: {user['email']}") ``` ### `text_completion(self, system: str, prompt: str, **kwargs: Any) -> str` Generar finalización de texto (no en tiempo real). Genera una respuesta de texto a partir de un modelo de lenguaje grande (LLM) dado un mensaje del sistema y un mensaje del usuario. Devuelve el texto de la respuesta completo. Nota: Este método no admite la transmisión. Para la generación de texto en tiempo real, utilice AsyncSocketFlowInstance.text_completion() en su lugar. **Argumentos:** `system`: Mensaje del sistema que define el comportamiento del LLM. `prompt`: Mensaje del usuario o pregunta. `**kwargs`: Parámetros adicionales específicos del servicio. **Devuelve:** str: Respuesta de texto generada completa. **Ejemplo:** ```python async_flow = await api.async_flow() flow = async_flow.id("default") # Generate text response = await flow.text_completion( system="You are a helpful assistant.", prompt="Explain quantum computing in simple terms." ) print(response) ``` ### `triples_query(self, s=None, p=None, o=None, user=None, collection=None, limit=100, **kwargs: Any)` Consultar triples RDF utilizando la coincidencia de patrones. Busca triples que coincidan con los patrones especificados de sujeto, predicado y/o objeto. Los patrones utilizan None como comodín para coincidir con cualquier valor. **Argumentos:** `s`: Patrón de sujeto (None para comodín) `p`: Patrón de predicado (None para comodín) `o`: Patrón de objeto (None para comodín) `user`: Identificador de usuario (None para todos los usuarios) `collection`: Identificador de colección (None para todas las colecciones) `limit`: Número máximo de triples a devolver (por defecto: 100) `**kwargs`: Parámetros adicionales específicos del servicio **Devuelve:** dict: Respuesta que contiene los triples coincidentes **Ejemplo:** ```python async_flow = await api.async_flow() flow = async_flow.id("default") # Find all triples with a specific predicate results = await flow.triples_query( p="knows", user="trustgraph", collection="social", limit=50 ) for triple in results.get("triples", []): print(f"{triple['s']} knows {triple['o']}") ``` -- ## `SocketClient` ```python from trustgraph.api import SocketClient ``` Cliente WebSocket sincrónico para operaciones de transmisión. Proporciona una interfaz sincrónica a los servicios TrustGraph basados en WebSocket, envolviendo la biblioteca de WebSockets asíncronos con generadores sincrónicos para facilitar su uso. Admite respuestas de transmisión de agentes, consultas RAG y finalizaciones de texto. Nota: Este es un envoltorio sincrónico alrededor de operaciones de WebSocket asíncronas. Para un soporte asíncrono real, utilice AsyncSocketClient en su lugar. ### Métodos ### `__init__(self, url: str, timeout: int, token: str | None) -> None` Inicializa el cliente WebSocket sincrónico. **Argumentos:** `url`: URL base para la API de TrustGraph (HTTP/HTTPS se convertirá a WS/WSS) `timeout`: Tiempo de espera de WebSocket en segundos `token`: Token de portador opcional para la autenticación ### `close(self) -> None` Cierra las conexiones WebSocket. Nota: La limpieza se gestiona automáticamente por los administradores de contexto en el código asíncrono. ### `flow(self, flow_id: str) -> 'SocketFlowInstance'` Obtiene una instancia de flujo para operaciones de transmisión de WebSocket. **Argumentos:** `flow_id`: Identificador de flujo **Devuelve:** SocketFlowInstance: Instancia de flujo con métodos de transmisión **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") # Stream agent responses for chunk in flow.agent(question="Hello", user="trustgraph", streaming=True): print(chunk.content, end='', flush=True) ``` -- ## `SocketFlowInstance` ```python from trustgraph.api import SocketFlowInstance ``` Instancia de flujo WebSocket sincrónico para operaciones de transmisión. Proporciona la misma interfaz que FlowInstance de REST, pero con soporte de transmisión basado en WebSocket para respuestas en tiempo real. Todos los métodos admiten un parámetro opcional `streaming` para habilitar la entrega incremental de resultados. ### Métodos ### `__init__(self, client: trustgraph.api.socket_client.SocketClient, flow_id: str) -> None` Inicializar instancia de flujo de socket. **Argumentos:** `client`: SocketClient padre `flow_id`: Identificador de flujo ### `agent(self, question: str, user: str, state: Dict[str, Any] | None = None, group: str | None = None, history: List[Dict[str, Any]] | None = None, streaming: bool = False, **kwargs: Any) -> Dict[str, Any] | Iterator[trustgraph.api.types.StreamingChunk]` Ejecutar una operación de agente con soporte de transmisión. Los agentes pueden realizar razonamientos de varios pasos con el uso de herramientas. Este método siempre devuelve fragmentos de transmisión (pensamientos, observaciones, respuestas) incluso cuando streaming=False, para mostrar el proceso de razonamiento del agente. **Argumentos:** `question`: Pregunta o instrucción del usuario `user`: Identificador del usuario `state`: Diccionario de estado opcional para conversaciones con estado `group`: Identificador de grupo opcional para contextos multiusuario `history`: Historial de conversación opcional como lista de diccionarios de mensajes `streaming`: Habilitar el modo de transmisión (predeterminado: False) `**kwargs`: Parámetros adicionales pasados al servicio del agente **Devuelve:** Iterator[StreamingChunk]: Flujo de pensamientos, observaciones y respuestas del agente **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") # Stream agent reasoning for chunk in flow.agent( question="What is quantum computing?", user="trustgraph", streaming=True ): if isinstance(chunk, AgentThought): print(f"[Thinking] {chunk.content}") elif isinstance(chunk, AgentObservation): print(f"[Observation] {chunk.content}") elif isinstance(chunk, AgentAnswer): print(f"[Answer] {chunk.content}") ``` ### `agent_explain(self, question: str, user: str, collection: str, state: Dict[str, Any] | None = None, group: str | None = None, history: List[Dict[str, Any]] | None = None, **kwargs: Any) -> Iterator[trustgraph.api.types.StreamingChunk | trustgraph.api.types.ProvenanceEvent]` Ejecutar una operación de agente con soporte de explicabilidad. Transmite tanto los fragmentos de contenido (AgentThought, AgentObservation, AgentAnswer) como los eventos de procedencia (ProvenanceEvent). Los eventos de procedencia contienen URIs que se pueden recuperar utilizando ExplainabilityClient para obtener información detallada sobre el proceso de razonamiento del agente. El rastro del agente consiste en: Sesión: La pregunta inicial y los metadatos de la sesión. Iteraciones: Cada ciclo de pensamiento/acción/observación. Conclusión: La respuesta final. **Argumentos:** `question`: Pregunta o instrucción del usuario. `user`: Identificador del usuario. `collection`: Identificador de la colección para el almacenamiento de la procedencia. `state`: Diccionario de estado opcional para conversaciones con estado. `group`: Identificador de grupo opcional para contextos multiusuario. `history`: Historial de conversación opcional como una lista de diccionarios de mensajes. `**kwargs`: Parámetros adicionales pasados al servicio del agente. `Yields`: `Union[StreamingChunk, ProvenanceEvent]`: Fragmentos del agente y eventos de procedencia. **Ejemplo:** ```python from trustgraph.api import Api, ExplainabilityClient, ProvenanceEvent from trustgraph.api import AgentThought, AgentObservation, AgentAnswer socket = api.socket() flow = socket.flow("default") explain_client = ExplainabilityClient(flow) provenance_ids = [] for item in flow.agent_explain( question="What is the capital of France?", user="trustgraph", collection="default" ): if isinstance(item, AgentThought): print(f"[Thought] {item.content}") elif isinstance(item, AgentObservation): print(f"[Observation] {item.content}") elif isinstance(item, AgentAnswer): print(f"[Answer] {item.content}") elif isinstance(item, ProvenanceEvent): provenance_ids.append(item.explain_id) # Fetch session trace after completion if provenance_ids: trace = explain_client.fetch_agent_trace( provenance_ids[0], # Session URI is first graph="urn:graph:retrieval", user="trustgraph", collection="default" ) ``` ### `document_embeddings_query(self, text: str, user: str, collection: str, limit: int = 10, **kwargs: Any) -> Dict[str, Any]` Consultar fragmentos de documentos utilizando similitud semántica. **Argumentos:** `text`: Texto de consulta para la búsqueda semántica `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección `limit`: Número máximo de resultados (por defecto: 10) `**kwargs`: Parámetros adicionales pasados al servicio **Retorna:** dict: Resultados de la consulta con los ID de los fragmentos de los documentos coincidentes **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") results = flow.document_embeddings_query( text="machine learning algorithms", user="trustgraph", collection="research-papers", limit=5 ) # results contains {"chunks": [{"chunk_id": "...", "score": 0.95}, ...]} ``` ### `document_rag(self, query: str, user: str, collection: str, doc_limit: int = 10, streaming: bool = False, **kwargs: Any) -> str | Iterator[str]` Ejecutar una consulta RAG basada en documentos con transmisión opcional. Utiliza incrustaciones vectoriales para encontrar fragmentos de documentos relevantes y luego genera una respuesta utilizando un LLM. El modo de transmisión entrega resultados de forma incremental. **Argumentos:** `query`: Consulta en lenguaje natural `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección `doc_limit`: Número máximo de fragmentos de documentos a recuperar (predeterminado: 10) `streaming`: Habilitar el modo de transmisión (predeterminado: Falso) `**kwargs`: Parámetros adicionales pasados al servicio **Retorna:** Union[str, Iterator[str]]: Respuesta completa o flujo de fragmentos de texto **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") # Streaming document RAG for chunk in flow.document_rag( query="Summarize the key findings", user="trustgraph", collection="research-papers", doc_limit=5, streaming=True ): print(chunk, end='', flush=True) ``` ### `document_rag_explain(self, query: str, user: str, collection: str, doc_limit: int = 10, **kwargs: Any) -> Iterator[trustgraph.api.types.RAGChunk | trustgraph.api.types.ProvenanceEvent]` Ejecutar una consulta RAG basada en documentos con soporte para la explicabilidad. Transmite tanto los fragmentos de contenido (RAGChunk) como los eventos de procedencia (ProvenanceEvent). Los eventos de procedencia contienen URIs que se pueden recuperar utilizando ExplainabilityClient para obtener información detallada sobre cómo se generó la respuesta. El rastro RAG del documento consiste en: Pregunta: La consulta del usuario Exploración: Fragmentos recuperados de la tienda de documentos (chunk_count) Síntesis: La respuesta generada **Argumentos:** `query`: Consulta en lenguaje natural `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección `doc_limit`: Número máximo de fragmentos de documento a recuperar (por defecto: 10) `**kwargs`: Parámetros adicionales pasados al servicio `Yields`: `Union[RAGChunk, ProvenanceEvent]`: Fragmentos de contenido y eventos de procedencia **Ejemplo:** ```python from trustgraph.api import Api, ExplainabilityClient, RAGChunk, ProvenanceEvent socket = api.socket() flow = socket.flow("default") explain_client = ExplainabilityClient(flow) for item in flow.document_rag_explain( query="Summarize the key findings", user="trustgraph", collection="research-papers", doc_limit=5 ): if isinstance(item, RAGChunk): print(item.content, end='', flush=True) elif isinstance(item, ProvenanceEvent): # Fetch entity details entity = explain_client.fetch_entity( item.explain_id, graph=item.explain_graph, user="trustgraph", collection="research-papers" ) print(f"Event: {entity}", file=sys.stderr) ``` ### `embeddings(self, texts: list, **kwargs: Any) -> Dict[str, Any]` Generar incrustaciones vectoriales para uno o más textos. **Argumentos:** `texts`: Lista de textos de entrada para incrustar. `**kwargs`: Parámetros adicionales pasados al servicio. **Retorna:** dict: Respuesta que contiene vectores (un conjunto por texto de entrada). **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") result = flow.embeddings(["quantum computing"]) vectors = result.get("vectors", []) ``` ### `graph_embeddings_query(self, text: str, user: str, collection: str, limit: int = 10, **kwargs: Any) -> Dict[str, Any]` Consultar entidades de un grafo de conocimiento utilizando similitud semántica. **Argumentos:** `text`: Texto de la consulta para la búsqueda semántica `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección `limit`: Número máximo de resultados (por defecto: 10) `**kwargs`: Parámetros adicionales pasados al servicio **Retorna:** dict: Resultados de la consulta con entidades similares **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") results = flow.graph_embeddings_query( text="physicist who discovered radioactivity", user="trustgraph", collection="scientists", limit=5 ) ``` ### `graph_rag(self, query: str, user: str, collection: str, max_subgraph_size: int = 1000, max_subgraph_count: int = 5, max_entity_distance: int = 3, streaming: bool = False, **kwargs: Any) -> str | Iterator[str]` Ejecutar una consulta RAG basada en grafos con transmisión opcional. Utiliza la estructura del grafo de conocimiento para encontrar el contexto relevante y luego genera una respuesta utilizando un LLM. El modo de transmisión entrega los resultados de forma incremental. **Argumentos:** `query`: Consulta en lenguaje natural `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección `max_subgraph_size`: Número máximo total de triples en el subgrafo (por defecto: 1000) `max_subgraph_count`: Número máximo de subgrafos (por defecto: 5) `max_entity_distance`: Profundidad máxima de recorrido (por defecto: 3) `streaming`: Habilitar el modo de transmisión (por defecto: False) `**kwargs`: Parámetros adicionales pasados al servicio **Retorna:** Union[str, Iterator[str]]: Respuesta completa o flujo de fragmentos de texto **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") # Streaming graph RAG for chunk in flow.graph_rag( query="Tell me about Marie Curie", user="trustgraph", collection="scientists", streaming=True ): print(chunk, end='', flush=True) ``` ### `graph_rag_explain(self, query: str, user: str, collection: str, max_subgraph_size: int = 1000, max_subgraph_count: int = 5, max_entity_distance: int = 3, **kwargs: Any) -> Iterator[trustgraph.api.types.RAGChunk | trustgraph.api.types.ProvenanceEvent]` Ejecutar consulta RAG basada en grafos con soporte de explicabilidad. Transmite tanto fragmentos de contenido (RAGChunk) como eventos de procedencia (ProvenanceEvent). Los eventos de procedencia contienen URIs que se pueden recuperar utilizando ExplainabilityClient para obtener información detallada sobre cómo se generó la respuesta. **Argumentos:** `query`: Consulta en lenguaje natural `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección `max_subgraph_size`: Número máximo total de triples en el subgrafo (predeterminado: 1000) `max_subgraph_count`: Número máximo de subgrafos (predeterminado: 5) `max_entity_distance`: Profundidad máxima de recorrido (predeterminado: 3) `**kwargs`: Parámetros adicionales pasados al servicio `Yields`: `Union[RAGChunk, ProvenanceEvent]`: Fragmentos de contenido y eventos de procedencia **Ejemplo:** ```python from trustgraph.api import Api, ExplainabilityClient, RAGChunk, ProvenanceEvent socket = api.socket() flow = socket.flow("default") explain_client = ExplainabilityClient(flow) provenance_ids = [] response_text = "" for item in flow.graph_rag_explain( query="Tell me about Marie Curie", user="trustgraph", collection="scientists" ): if isinstance(item, RAGChunk): response_text += item.content print(item.content, end='', flush=True) elif isinstance(item, ProvenanceEvent): provenance_ids.append(item.provenance_id) # Fetch explainability details for prov_id in provenance_ids: entity = explain_client.fetch_entity( prov_id, graph="urn:graph:retrieval", user="trustgraph", collection="scientists" ) print(f"Entity: {entity}") ``` ### `mcp_tool(self, name: str, parameters: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]` Ejecutar una herramienta de Protocolo de Contexto de Modelo (MCP). **Argumentos:** `name`: Nombre/identificador de la herramienta `parameters`: Diccionario de parámetros de la herramienta `**kwargs`: Parámetros adicionales pasados al servicio **Retorna:** dict: Resultado de la ejecución de la herramienta **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") result = flow.mcp_tool( name="search-web", parameters={"query": "latest AI news", "limit": 5} ) ``` ### `prompt(self, id: str, variables: Dict[str, str], streaming: bool = False, **kwargs: Any) -> str | Iterator[str]` Ejecutar una plantilla de prompt con transmisión opcional. **Argumentos:** `id`: Identificador de la plantilla de prompt. `variables`: Diccionario de mapeos de nombres de variables a valores. `streaming`: Habilitar el modo de transmisión (predeterminado: False). `**kwargs`: Parámetros adicionales pasados al servicio. **Retorna:** Union[str, Iterator[str]]: Respuesta completa o flujo de fragmentos de texto. **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") # Streaming prompt execution for chunk in flow.prompt( id="summarize-template", variables={"topic": "quantum computing", "length": "brief"}, streaming=True ): print(chunk, end='', flush=True) ``` ### `row_embeddings_query(self, text: str, schema_name: str, user: str = 'trustgraph', collection: str = 'default', index_name: str | None = None, limit: int = 10, **kwargs: Any) -> Dict[str, Any]` Consulta datos de filas utilizando la similitud semántica en campos indexados. Encuentra filas cuyos valores de campos indexados son semánticamente similares a el texto de entrada, utilizando incrustaciones vectoriales. Esto permite la coincidencia difusa/semántica en datos estructurados. **Argumentos:** `text`: Texto de consulta para la búsqueda semántica `schema_name`: Nombre del esquema para buscar `user`: Identificador de usuario/espacio de claves (predeterminado: "trustgraph") `collection`: Identificador de colección (predeterminado: "default") `index_name`: Nombre de índice opcional para filtrar la búsqueda a un índice específico `limit`: Número máximo de resultados (predeterminado: 10) `**kwargs`: Parámetros adicionales pasados al servicio **Retorna:** dict: Resultados de la consulta con coincidencias que contienen index_name, index_value, text y score **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") # Search for customers by name similarity results = flow.row_embeddings_query( text="John Smith", schema_name="customers", user="trustgraph", collection="sales", limit=5 ) # Filter to specific index results = flow.row_embeddings_query( text="machine learning engineer", schema_name="employees", index_name="job_title", limit=10 ) ``` ### `rows_query(self, query: str, user: str, collection: str, variables: Dict[str, Any] | None = None, operation_name: str | None = None, **kwargs: Any) -> Dict[str, Any]` Ejecutar una consulta GraphQL contra filas estructuradas. **Argumentos:** `query`: Cadena de consulta GraphQL `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección `variables`: Diccionario opcional de variables de consulta `operation_name`: Nombre de operación opcional para documentos de múltiples operaciones `**kwargs`: Parámetros adicionales pasados al servicio **Retorna:** dict: Respuesta GraphQL con datos, errores y/o extensiones **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") query = ''' { scientists(limit: 10) { name field discoveries } } ''' result = flow.rows_query( query=query, user="trustgraph", collection="scientists" ) ``` ### `text_completion(self, system: str, prompt: str, streaming: bool = False, **kwargs) -> str | Iterator[str]` Ejecutar la finalización de texto con transmisión opcional. **Argumentos:** `system`: Instrucción del sistema que define el comportamiento del asistente. `prompt`: Instrucción/pregunta del usuario. `streaming`: Habilitar el modo de transmisión (predeterminado: False). `**kwargs`: Parámetros adicionales pasados al servicio. **Retorna:** Union[str, Iterator[str]]: Respuesta completa o flujo de fragmentos de texto. **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") # Non-streaming response = flow.text_completion( system="You are helpful", prompt="Explain quantum computing", streaming=False ) print(response) # Streaming for chunk in flow.text_completion( system="You are helpful", prompt="Explain quantum computing", streaming=True ): print(chunk, end='', flush=True) ``` ### `triples_query(self, s: str | Dict[str, Any] | None = None, p: str | Dict[str, Any] | None = None, o: str | Dict[str, Any] | None = None, g: str | None = None, user: str | None = None, collection: str | None = None, limit: int = 100, **kwargs: Any) -> List[Dict[str, Any]]` Consultar triples del grafo de conocimiento utilizando la coincidencia de patrones. **Argumentos:** `s`: Filtro de sujeto - Cadena URI, diccionario de términos o None para comodín. `p`: Filtro de predicado - Cadena URI, diccionario de términos o None para comodín. `o`: Filtro de objeto - Cadena URI/literal, diccionario de términos o None para comodín. `g`: Filtro de grafo con nombre - Cadena URI o None para todos los grafos. `user`: Identificador de usuario/espacio de claves (opcional). `collection`: Identificador de colección (opcional). `limit`: Número máximo de resultados a devolver (por defecto: 100). `**kwargs`: Parámetros adicionales pasados al servicio. **Retorna:** List[Dict]: Lista de triples coincidentes en formato de cable. **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") # Find all triples about a specific subject triples = flow.triples_query( s="http://example.org/person/marie-curie", user="trustgraph", collection="scientists" ) # Query with named graph filter triples = flow.triples_query( s="urn:trustgraph:session:abc123", g="urn:graph:retrieval", user="trustgraph", collection="default" ) ``` ### `triples_query_stream(self, s: str | Dict[str, Any] | None = None, p: str | Dict[str, Any] | None = None, o: str | Dict[str, Any] | None = None, g: str | None = None, user: str | None = None, collection: str | None = None, limit: int = 100, batch_size: int = 20, **kwargs: Any) -> Iterator[List[Dict[str, Any]]]` Consultar triples del grafo de conocimiento con lotes de transmisión. Produce lotes de triples a medida que llegan, reduciendo el tiempo para obtener el primer resultado y la sobrecarga de memoria para conjuntos de resultados grandes. **Argumentos:** `s`: Filtro de sujeto - Cadena URI, diccionario de términos o None para comodín `p`: Filtro de predicado - Cadena URI, diccionario de términos o None para comodín `o`: Filtro de objeto - Cadena URI/literal, diccionario de términos o None para comodín `g`: Filtro de grafo con nombre - Cadena URI o None para todos los grafos `user`: Identificador de usuario/espacio de claves (opcional) `collection`: Identificador de colección (opcional) `limit`: Número máximo de resultados a devolver (por defecto: 100) `batch_size`: Triples por lote (por defecto: 20) `**kwargs`: Parámetros adicionales pasados al servicio `Yields`: `List[Dict]`: Lotes de triples en formato de cable **Ejemplo:** ```python socket = api.socket() flow = socket.flow("default") for batch in flow.triples_query_stream( user="trustgraph", collection="default" ): for triple in batch: print(triple["s"], triple["p"], triple["o"]) ``` -- ## `AsyncSocketClient` ```python from trustgraph.api import AsyncSocketClient ``` Cliente WebSocket asíncrono ### Métodos ### `__init__(self, url: str, timeout: int, token: str | None)` Inicializar self. Consulte help(type(self)) para obtener la firma precisa. ### `aclose(self)` Cerrar conexión WebSocket ### `flow(self, flow_id: str)` Obtener la instancia de flujo asíncrono para operaciones de WebSocket -- ## `AsyncSocketFlowInstance` ```python from trustgraph.api import AsyncSocketFlowInstance ``` Flujo de WebSocket asíncrono. ### Métodos ### `__init__(self, client: trustgraph.api.async_socket_client.AsyncSocketClient, flow_id: str)` Inicializar self. Consulte help(type(self)) para obtener la firma correcta. ### `agent(self, question: str, user: str, state: Dict[str, Any] | None = None, group: str | None = None, history: list | None = None, streaming: bool = False, **kwargs) -> Dict[str, Any] | AsyncIterator` Agente con transmisión opcional. ### `document_rag(self, query: str, user: str, collection: str, doc_limit: int = 10, streaming: bool = False, **kwargs)` Documento RAG con transmisión opcional. ### `embeddings(self, texts: list, **kwargs)` Generar incrustaciones de texto. ### `graph_embeddings_query(self, text: str, user: str, collection: str, limit: int = 10, **kwargs)` Consultar incrustaciones de grafos para búsqueda semántica. ### `graph_rag(self, query: str, user: str, collection: str, max_subgraph_size: int = 1000, max_subgraph_count: int = 5, max_entity_distance: int = 3, streaming: bool = False, **kwargs)` RAG de grafos con transmisión opcional. ### `mcp_tool(self, name: str, parameters: Dict[str, Any], **kwargs)` Ejecutar herramienta MCP. ### `prompt(self, id: str, variables: Dict[str, str], streaming: bool = False, **kwargs)` Ejecutar prompt con transmisión opcional. ### `row_embeddings_query(self, text: str, schema_name: str, user: str = 'trustgraph', collection: str = 'default', index_name: str | None = None, limit: int = 10, **kwargs)` Consultar incrustaciones de filas para búsqueda semántica en datos estructurados. ### `rows_query(self, query: str, user: str, collection: str, variables: Dict | None = None, operation_name: str | None = None, **kwargs)` Consulta GraphQL contra filas estructuradas. ### `text_completion(self, system: str, prompt: str, streaming: bool = False, **kwargs)` Completar texto con transmisión opcional. ### `triples_query(self, s=None, p=None, o=None, user=None, collection=None, limit=100, **kwargs)` Consulta de patrones triples. -- ### `build_term(value: Any, term_type: str | None = None, datatype: str | None = None, language: str | None = None) -> Dict[str, Any] | None` Construir un diccionario de términos en formato de cable a partir de un valor. Reglas de detección automática (cuando term_type es None): Ya es un diccionario con la clave 't' -> devolver tal cual (ya es un Term) Comienza con http://, https://, urn: -> IRI Está encerrado entre < (por ejemplo, ) -> IRI (se eliminan los corchetes) Cualquier otra cosa -> literal **Argumentos:** `value`: El valor del término (cadena, diccionario o None). `term_type`: Uno de 'iri', 'literal' o None para la detección automática. `datatype`: Tipo de datos para objetos literales (por ejemplo, xsd:integer). `language`: Etiqueta de idioma para objetos literales (por ejemplo, en). **Devuelve:** dict: Diccionario de términos en formato de cable, o None si el valor es None. -- ## `BulkClient` ```python from trustgraph.api import BulkClient ``` Cliente para operaciones masivas sincrónicas para la importación/exportación. Proporciona una transferencia de datos masiva eficiente a través de WebSocket para conjuntos de datos grandes. Envuelve las operaciones asíncronas de WebSocket con generadores sincrónicos para facilitar su uso. Nota: Para un soporte asíncrono real, utilice AsyncBulkClient en su lugar. ### Métodos ### `__init__(self, url: str, timeout: int, token: str | None) -> None` Inicializa el cliente de operaciones masivas sincrónico. **Argumentos:** `url`: URL base para la API de TrustGraph (HTTP/HTTPS se convertirá a WS/WSS) `timeout`: Tiempo de espera de WebSocket en segundos `token`: Token de portador opcional para la autenticación ### `close(self) -> None` Cierra las conexiones. ### `export_document_embeddings(self, flow: str, **kwargs: Any) -> Iterator[Dict[str, Any]]` Exporta masivamente las incrustaciones de documentos desde un flujo. Descarga de forma eficiente todas las incrustaciones de fragmentos de documentos a través de la transmisión de WebSocket. **Argumentos:** `flow`: Identificador del flujo `**kwargs`: Parámetros adicionales (reservados para uso futuro) **Devuelve:** Iterator[Dict[str, Any]]: Flujo de diccionarios de incrustaciones **Ejemplo:** ```python bulk = api.bulk() # Export and process document embeddings for embedding in bulk.export_document_embeddings(flow="default"): chunk_id = embedding.get("chunk_id") vector = embedding.get("embedding") print(f"{chunk_id}: {len(vector)} dimensions") ``` ### `export_entity_contexts(self, flow: str, **kwargs: Any) -> Iterator[Dict[str, Any]]` Exportación masiva de contextos de entidades desde un flujo. Descarga de manera eficiente toda la información del contexto de la entidad a través de transmisión WebSocket. **Argumentos:** `flow`: Identificador del flujo. `**kwargs`: Parámetros adicionales (reservados para uso futuro). **Retorna:** Iterator[Dict[str, Any]]: Flujo de diccionarios de contexto. **Ejemplo:** ```python bulk = api.bulk() # Export and process entity contexts for context in bulk.export_entity_contexts(flow="default"): entity = context.get("entity") text = context.get("context") print(f"{entity}: {text[:100]}...") ``` ### `export_graph_embeddings(self, flow: str, **kwargs: Any) -> Iterator[Dict[str, Any]]` Exportación masiva de incrustaciones de grafos desde un flujo. Descarga de manera eficiente todas las incrustaciones de entidades de grafos a través de transmisión WebSocket. **Argumentos:** `flow`: Identificador del flujo. `**kwargs`: Parámetros adicionales (reservados para uso futuro). **Retorna:** Iterator[Dict[str, Any]]: Flujo de diccionarios de incrustaciones. **Ejemplo:** ```python bulk = api.bulk() # Export and process embeddings for embedding in bulk.export_graph_embeddings(flow="default"): entity = embedding.get("entity") vector = embedding.get("embedding") print(f"{entity}: {len(vector)} dimensions") ``` ### `export_triples(self, flow: str, **kwargs: Any) -> Iterator[trustgraph.api.types.Triple]` Exportación masiva de triples RDF desde un flujo. Descarga de manera eficiente todos los triples a través de transmisión WebSocket. **Argumentos:** `flow`: Identificador del flujo. `**kwargs`: Parámetros adicionales (reservados para uso futuro). **Retorna:** Iterator[Triple]: Flujo de objetos Triple. **Ejemplo:** ```python bulk = api.bulk() # Export and process triples for triple in bulk.export_triples(flow="default"): print(f"{triple.s} -> {triple.p} -> {triple.o}") ``` ### `import_document_embeddings(self, flow: str, embeddings: Iterator[Dict[str, Any]], **kwargs: Any) -> None` Importación masiva de incrustaciones de documentos en un flujo. Carga de manera eficiente las incrustaciones de fragmentos de documentos a través de transmisión WebSocket para su uso en consultas RAG de documentos. **Argumentos:** `flow`: Identificador del flujo. `embeddings`: Iterador que produce diccionarios de incrustaciones. `**kwargs`: Parámetros adicionales (reservados para uso futuro). **Ejemplo:** ```python bulk = api.bulk() # Generate document embeddings to import def doc_embedding_generator(): yield {"chunk_id": "doc1/p0/c0", "embedding": [0.1, 0.2, ...]} yield {"chunk_id": "doc1/p0/c1", "embedding": [0.3, 0.4, ...]} # ... more embeddings bulk.import_document_embeddings( flow="default", embeddings=doc_embedding_generator() ) ``` ### `import_entity_contexts(self, flow: str, contexts: Iterator[Dict[str, Any]], metadata: Dict[str, Any] | None = None, batch_size: int = 100, **kwargs: Any) -> None` Importación masiva de contextos de entidades en un flujo. Carga de manera eficiente la información del contexto de la entidad a través de transmisión WebSocket. Los contextos de entidades proporcionan un contexto textual adicional sobre las entidades del gráfico para mejorar el rendimiento de RAG. **Argumentos:** `flow`: Identificador del flujo. `contexts`: Iterador que devuelve diccionarios de contexto. `metadata`: Diccionario de metadatos con id, metadatos, usuario, colección. `batch_size`: Número de contextos por lote (por defecto 100). `**kwargs`: Parámetros adicionales (reservados para uso futuro). **Ejemplo:** ```python bulk = api.bulk() # Generate entity contexts to import def context_generator(): yield {"entity": {"v": "entity1", "e": True}, "context": "Description..."} yield {"entity": {"v": "entity2", "e": True}, "context": "Description..."} # ... more contexts bulk.import_entity_contexts( flow="default", contexts=context_generator(), metadata={"id": "doc1", "metadata": [], "user": "user1", "collection": "default"} ) ``` ### `import_graph_embeddings(self, flow: str, embeddings: Iterator[Dict[str, Any]], **kwargs: Any) -> None` Importación masiva de incrustaciones de grafos en un flujo. Carga de manera eficiente las incrustaciones de entidades de grafos a través de transmisión WebSocket. **Argumentos:** `flow`: Identificador del flujo. `embeddings`: Iterador que produce diccionarios de incrustaciones. `**kwargs`: Parámetros adicionales (reservados para uso futuro). **Ejemplo:** ```python bulk = api.bulk() # Generate embeddings to import def embedding_generator(): yield {"entity": "entity1", "embedding": [0.1, 0.2, ...]} yield {"entity": "entity2", "embedding": [0.3, 0.4, ...]} # ... more embeddings bulk.import_graph_embeddings( flow="default", embeddings=embedding_generator() ) ``` ### `import_rows(self, flow: str, rows: Iterator[Dict[str, Any]], **kwargs: Any) -> None` Importación masiva de filas estructuradas en un flujo. Carga de manera eficiente datos estructurados a través de transmisión WebSocket para su uso en consultas GraphQL. **Argumentos:** `flow`: Identificador del flujo `rows`: Iterador que produce diccionarios de filas `**kwargs`: Parámetros adicionales (reservados para uso futuro) **Ejemplo:** ```python bulk = api.bulk() # Generate rows to import def row_generator(): yield {"id": "row1", "name": "Row 1", "value": 100} yield {"id": "row2", "name": "Row 2", "value": 200} # ... more rows bulk.import_rows( flow="default", rows=row_generator() ) ``` ### `import_triples(self, flow: str, triples: Iterator[trustgraph.api.types.Triple], metadata: Dict[str, Any] | None = None, batch_size: int = 100, **kwargs: Any) -> None` Importación masiva de triples RDF en un flujo. Carga de manera eficiente un gran número de triples a través de transmisión WebSocket. **Argumentos:** `flow`: Identificador del flujo. `triples`: Iterador que produce objetos Triple. `metadata`: Diccionario de metadatos con id, metadatos, usuario, colección. `batch_size`: Número de triples por lote (por defecto 100). `**kwargs`: Parámetros adicionales (reservados para uso futuro). **Ejemplo:** ```python from trustgraph.api import Triple bulk = api.bulk() # Generate triples to import def triple_generator(): yield Triple(s="subj1", p="pred", o="obj1") yield Triple(s="subj2", p="pred", o="obj2") # ... more triples # Import triples bulk.import_triples( flow="default", triples=triple_generator(), metadata={"id": "doc1", "metadata": [], "user": "user1", "collection": "default"} ) ``` -- ## `AsyncBulkClient` ```python from trustgraph.api import AsyncBulkClient ``` Cliente para operaciones masivas asíncronas. ### Métodos ### `__init__(self, url: str, timeout: int, token: str | None) -> None` Inicializar self. Consulte help(type(self)) para obtener la firma precisa. ### `aclose(self) -> None` Cerrar conexiones. ### `export_document_embeddings(self, flow: str, **kwargs: Any) -> AsyncIterator[Dict[str, Any]]` Exportación masiva de incrustaciones de documentos a través de WebSocket. ### `export_entity_contexts(self, flow: str, **kwargs: Any) -> AsyncIterator[Dict[str, Any]]` Exportación masiva de contextos de entidades a través de WebSocket. ### `export_graph_embeddings(self, flow: str, **kwargs: Any) -> AsyncIterator[Dict[str, Any]]` Exportación masiva de incrustaciones de grafos a través de WebSocket. ### `export_triples(self, flow: str, **kwargs: Any) -> AsyncIterator[trustgraph.api.types.Triple]` Exportación masiva de triples a través de WebSocket. ### `import_document_embeddings(self, flow: str, embeddings: AsyncIterator[Dict[str, Any]], **kwargs: Any) -> None` Importación masiva de incrustaciones de documentos a través de WebSocket. ### `import_entity_contexts(self, flow: str, contexts: AsyncIterator[Dict[str, Any]], **kwargs: Any) -> None` Importación masiva de contextos de entidades a través de WebSocket. ### `import_graph_embeddings(self, flow: str, embeddings: AsyncIterator[Dict[str, Any]], **kwargs: Any) -> None` Importación masiva de incrustaciones de grafos a través de WebSocket. ### `import_rows(self, flow: str, rows: AsyncIterator[Dict[str, Any]], **kwargs: Any) -> None` Importación masiva de filas a través de WebSocket. ### `import_triples(self, flow: str, triples: AsyncIterator[trustgraph.api.types.Triple], **kwargs: Any) -> None` Importación masiva de triples a través de WebSocket. -- ## `Metrics` ```python from trustgraph.api import Metrics ``` Cliente de métricas sincrónicas ### Métodos ### `__init__(self, url: str, timeout: int, token: str | None) -> None` Inicializar self. Consulte help(type(self)) para obtener la firma precisa. ### `get(self) -> str` Obtener métricas de Prometheus como texto -- ## `AsyncMetrics` ```python from trustgraph.api import AsyncMetrics ``` Cliente de métricas asíncronas ### Métodos ### `__init__(self, url: str, timeout: int, token: str | None) -> None` Inicializar self. Consulte help(type(self)) para obtener la firma correcta. ### `aclose(self) -> None` Cerrar conexiones ### `get(self) -> str` Obtener métricas de Prometheus como texto -- ## `ExplainabilityClient` ```python from trustgraph.api import ExplainabilityClient ``` Cliente para obtener entidades de explicabilidad con manejo de consistencia eventual. Utiliza la detección de quiescencia: obtener, esperar, obtener de nuevo, comparar. Si los resultados son los mismos, los datos son estables. ### Métodos ### `__init__(self, flow_instance, retry_delay: float = 0.2, max_retries: int = 10)` Inicializar el cliente de explicabilidad. **Argumentos:** `flow_instance`: Una instancia de SocketFlowInstance para consultar triples. `retry_delay`: Retraso entre reintentos en segundos (por defecto: 0.2). `max_retries`: Número máximo de intentos de reintento (por defecto: 10). ### `detect_session_type(self, session_uri: str, graph: str | None = None, user: str | None = None, collection: str | None = None) -> str` Detectar si una sesión es de tipo GraphRAG o Agent. **Argumentos:** `session_uri`: La URI de la sesión/pregunta. `graph`: Grafo nombrado. `user`: Identificador de usuario/espacio de claves. `collection`: Identificador de colección. **Retorna:** "graphrag" o "agent". ### `fetch_agent_trace(self, session_uri: str, graph: str | None = None, user: str | None = None, collection: str | None = None, api: Any = None, max_content: int = 10000) -> Dict[str, Any]` Obtener el rastro completo del Agent a partir de una URI de sesión. Sigue la cadena de procedencia: Pregunta -> Análisis(es) -> Conclusión. **Argumentos:** `session_uri`: La URI de la sesión/pregunta del agente. `graph`: Grafo nombrado (por defecto: urn:graph:retrieval). `user`: Identificador de usuario/espacio de claves. `collection`: Identificador de colección. `api`: Instancia de la API de TrustGraph para el acceso al bibliotecario (opcional). `max_content`: Longitud máxima del contenido para la conclusión. **Retorna:** Diccionario con la pregunta, las iteraciones (lista de Análisis) y las entidades de conclusión. ### `fetch_docrag_trace(self, question_uri: str, graph: str | None = None, user: str | None = None, collection: str | None = None, api: Any = None, max_content: int = 10000) -> Dict[str, Any]` Obtener el rastro completo de DocumentRAG a partir de una URI de pregunta. Sigue la cadena de procedencia: Pregunta -> Fundamentación -> Exploración -> Síntesis. **Argumentos:** `question_uri`: La URI de la entidad de pregunta. `graph`: Grafo nombrado (por defecto: urn:graph:retrieval). `user`: Identificador de usuario/espacio de claves. `collection`: Identificador de colección. `api`: Instancia de la API de TrustGraph para el acceso al bibliotecario (opcional). `max_content`: Longitud máxima del contenido para la síntesis. **Retorna:** Diccionario con la pregunta, la fundamentación, la exploración y las entidades de síntesis. ### `fetch_document_content(self, document_uri: str, api: Any, user: str | None = None, max_content: int = 10000) -> str` Obtener contenido del bibliotecario por URI de documento. **Argumentos:** `document_uri`: La URI del documento en el bibliotecario. `api`: Instancia de la API de TrustGraph para el acceso al bibliotecario. `user`: Identificador de usuario para el bibliotecario. `max_content`: Longitud máxima del contenido a retornar. **Retorna:** El contenido del documento como una cadena. ### `fetch_edge_selection(self, uri: str, graph: str | None = None, user: str | None = None, collection: str | None = None) -> trustgraph.api.explainability.EdgeSelection | None` Obtener una entidad de selección de borde (utilizada por Focus). **Argumentos:** `uri`: La URI de la selección de borde. `graph`: Grafo nombrado a consultar. `user`: Identificador de usuario/espacio de claves. `collection`: Identificador de colección. **Retorna:** EdgeSelection o None si no se encuentra. ### `fetch_entity(self, uri: str, graph: str | None = None, user: str | None = None, collection: str | None = None) -> trustgraph.api.explainability.ExplainEntity | None` Obtener una entidad de explicabilidad por URI con manejo de consistencia eventual. Utiliza la detección de quiescencia: 1. Obtener triples para el URI 2. Si no hay resultados, reintentar 3. Si hay resultados, esperar y obtener de nuevo 4. Si los resultados son los mismos, los datos son estables: analizar y devolver 5. Si los resultados son diferentes, los datos aún se están escribiendo: reintentar **Argumentos:** `uri`: El URI de la entidad a obtener `graph`: Grafo con nombre para consultar (por ejemplo, "urn:graph:retrieval") `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección **Devuelve:** Subclase ExplainEntity o None si no se encuentra ### `fetch_focus_with_edges(self, uri: str, graph: str | None = None, user: str | None = None, collection: str | None = None) -> trustgraph.api.explainability.Focus | None` Obtener una entidad Focus y todas sus selecciones de aristas. **Argumentos:** `uri`: El URI de la entidad Focus `graph`: Grafo con nombre para consultar `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección **Devuelve:** Focus con edge_selections pobladas, o None ### `fetch_graphrag_trace(self, question_uri: str, graph: str | None = None, user: str | None = None, collection: str | None = None, api: Any = None, max_content: int = 10000) -> Dict[str, Any]` Obtener el rastro completo de GraphRAG a partir de un URI de pregunta. Sigue la cadena de procedencia: Pregunta -> Grounding -> Exploración -> Focus -> Síntesis **Argumentos:** `question_uri`: El URI de la entidad de pregunta `graph`: Grafo (por defecto: urn:graph:retrieval) `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección `api`: Instancia de la API TrustGraph para el acceso de bibliotecario (opcional) `max_content`: Longitud máxima del contenido para la síntesis **Devuelve:** Diccionario con las entidades de pregunta, grounding, exploración, focus y síntesis ### `list_sessions(self, graph: str | None = None, user: str | None = None, collection: str | None = None, limit: int = 50) -> List[trustgraph.api.explainability.Question]` Listar todas las sesiones de explicabilidad (preguntas) en una colección. **Argumentos:** `graph`: Grafo (por defecto: urn:graph:retrieval) `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección `limit`: Número máximo de sesiones a devolver **Devuelve:** Lista de entidades de Pregunta ordenadas por marca de tiempo (más reciente primero) ### `resolve_edge_labels(self, edge: Dict[str, str], user: str | None = None, collection: str | None = None) -> Tuple[str, str, str]` Resolver las etiquetas para todos los componentes de una tripleta de arista. **Argumentos:** `edge`: Diccionario con claves "s", "p" y "o" `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección **Devuelve:** Tupla de (s_label, p_label, o_label) ### `resolve_label(self, uri: str, user: str | None = None, collection: str | None = None) -> str` Resolver rdfs:label para un URI, con almacenamiento en caché. **Argumentos:** `uri`: El URI para obtener la etiqueta `user`: Identificador de usuario/espacio de claves `collection`: Identificador de colección **Devuelve:** La etiqueta si se encuentra, de lo contrario, el propio URI -- ## `ExplainEntity` ```python from trustgraph.api import ExplainEntity ``` Clase base para entidades de explicabilidad. **Campos:** `uri`: `entity_type`: ### Métodos ### `__init__(self, uri: str, entity_type: str = '') -> None` Inicializa self. Consulte help(type(self)) para obtener la firma precisa. -- ## `Question` ```python from trustgraph.api import Question ``` Entidad de pregunta: la consulta del usuario que inició la sesión. **Campos:** `uri`: `entity_type`: `query`: `timestamp`: `question_type`: ### Métodos ### `__init__(self, uri: str, entity_type: str = '', query: str = '', timestamp: str = '', question_type: str = '') -> None` Inicializar self. Consulte help(type(self)) para obtener la firma precisa. -- ## `Exploration` ```python from trustgraph.api import Exploration ``` Entidad de exploración: bordes/fragmentos recuperados del almacén de conocimiento. **Campos:** `uri`: `entity_type`: `edge_count`: `chunk_count`: `entities`: typing.List[str] ### Métodos ### `__init__(self, uri: str, entity_type: str = '', edge_count: int = 0, chunk_count: int = 0, entities: List[str] = ) -> None` Inicializa self. Consulte help(type(self)) para obtener la firma precisa. -- ## `Focus` ```python from trustgraph.api import Focus ``` Entidad de enfoque: bordes seleccionados con razonamiento LLM (solo GraphRAG). **Campos:** `uri`: `entity_type`: `selected_edge_uris`: typing.List[str] `edge_selections`: typing.List[trustgraph.api.explainability.EdgeSelection] ### Métodos ### `__init__(self, uri: str, entity_type: str = '', selected_edge_uris: List[str] = , edge_selections: List[trustgraph.api.explainability.EdgeSelection] = ) -> None` Inicializa self. Consulta help(type(self)) para obtener la firma precisa. -- ## `Synthesis` ```python from trustgraph.api import Synthesis ``` Entidad de síntesis: la respuesta final. **Campos:** `uri`: `entity_type`: `document`: ### Métodos ### `__init__(self, uri: str, entity_type: str = '', document: str = '') -> None` Inicializa self. Consulta help(type(self)) para obtener la firma precisa. -- ## `Analysis` ```python from trustgraph.api import Analysis ``` Entidad de análisis: un ciclo de pensar/actuar/observar (solo para el Agente). **Campos:** `uri`: `entity_type`: `action`: `arguments`: `thought`: `observation`: ### Métodos ### `__init__(self, uri: str, entity_type: str = '', action: str = '', arguments: str = '', thought: str = '', observation: str = '') -> None` Inicializa self. Consulte help(type(self)) para obtener la firma correcta. -- ## `Conclusion` ```python from trustgraph.api import Conclusion ``` Conclusión de la entidad - respuesta final (solo para el agente). **Campos:** `uri`: `entity_type`: `document`: ### Métodos ### `__init__(self, uri: str, entity_type: str = '', document: str = '') -> None` Inicializa self. Consulta help(type(self)) para obtener la firma precisa. -- ## `EdgeSelection` ```python from trustgraph.api import EdgeSelection ``` Un borde seleccionado con razonamiento del paso GraphRAG Focus. **Campos:** `uri`: `edge`: typing.Dict[str, str] | None `reasoning`: ### Métodos ### `__init__(self, uri: str, edge: Dict[str, str] | None = None, reasoning: str = '') -> None` Inicializa self. Consulta help(type(self)) para obtener la firma precisa. -- ### `wire_triples_to_tuples(wire_triples: List[Dict[str, Any]]) -> List[Tuple[str, str, Any]]` Convierte las triples en formato de cable a tuplas (s, p, o). -- ### `extract_term_value(term: Dict[str, Any]) -> Any` Extrae el valor de un diccionario de términos en formato de cable. -- ## `Triple` ```python from trustgraph.api import Triple ``` Triple RDF que representa una declaración de un grafo de conocimiento. **Campos:** `s`: `p`: `o`: ### Métodos ### `__init__(self, s: str, p: str, o: str) -> None` Inicializa self. Consulte help(type(self)) para obtener la firma precisa. -- ## `Uri` ```python from trustgraph.api import Uri ``` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Crea un nuevo objeto de cadena a partir del objeto dado. Si se especifica encoding o errors, entonces el objeto debe exponer un búfer de datos que se decodificará utilizando la codificación y el controlador de errores especificados. De lo contrario, devuelve el resultado de object.__str__() (si está definido) o repr(object). encoding tiene como valor predeterminado 'utf-8'. errors tiene como valor predeterminado 'strict'. ### Métodos ### `is_literal(self)` ### `is_triple(self)` ### `is_uri(self)` -- ## `Literal` ```python from trustgraph.api import Literal ``` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Crea un nuevo objeto de cadena a partir del objeto dado. Si se especifica encoding o errors, entonces el objeto debe exponer un búfer de datos que se decodificará utilizando la codificación y el controlador de errores especificados. De lo contrario, devuelve el resultado de object.__str__() (si está definido) o repr(object). encoding tiene como valor predeterminado 'utf-8'. errors tiene como valor predeterminado 'strict'. ### Métodos ### `is_literal(self)` ### `is_triple(self)` ### `is_uri(self)` -- ## `ConfigKey` ```python from trustgraph.api import ConfigKey ``` Identificador de clave de configuración. **Campos:** `type`: `key`: ### Métodos ### `__init__(self, type: str, key: str) -> None` Inicializa self. Consulte help(type(self)) para obtener la firma precisa. -- ## `ConfigValue` ```python from trustgraph.api import ConfigValue ``` Par clave-valor de configuración. **Campos:** `type`: `key`: `value`: ### Métodos ### `__init__(self, type: str, key: str, value: str) -> None` Inicializa self. Consulte help(type(self)) para obtener la firma precisa. -- ## `DocumentMetadata` ```python from trustgraph.api import DocumentMetadata ``` Metadatos para un documento en la biblioteca. **Atributos:** `parent_id: Parent document ID for child documents (empty for top`: level docs) **Campos:** `id`: `time`: `kind`: `title`: `comments`: `metadata`: typing.List[trustgraph.api.types.Triple] `user`: `tags`: typing.List[str] `parent_id`: `document_type`: ### Métodos ### `__init__(self, id: str, time: datetime.datetime, kind: str, title: str, comments: str, metadata: List[trustgraph.api.types.Triple], user: str, tags: List[str], parent_id: str = '', document_type: str = 'source') -> None` Inicializar self. Consulte help(type(self)) para obtener la firma correcta. -- ## `ProcessingMetadata` ```python from trustgraph.api import ProcessingMetadata ``` Metadatos para un trabajo de procesamiento de documentos activo. **Campos:** `id`: `document_id`: `time`: `flow`: `user`: `collection`: `tags`: typing.List[str] ### Métodos ### `__init__(self, id: str, document_id: str, time: datetime.datetime, flow: str, user: str, collection: str, tags: List[str]) -> None` Inicializa self. Consulte help(type(self)) para obtener la firma correcta. -- ## `CollectionMetadata` ```python from trustgraph.api import CollectionMetadata ``` Metadatos para una colección de datos. Las colecciones proporcionan un agrupamiento lógico y un aislamiento para documentos y datos de grafos de conocimiento. **Atributos:** `name: Human`: nombre de colección legible **Campos:** `user`: `collection`: `name`: `description`: `tags`: typing.List[str] ### Métodos ### `__init__(self, user: str, collection: str, name: str, description: str, tags: List[str]) -> None` Inicializar self. Consulte help(type(self)) para obtener la firma precisa. -- ## `StreamingChunk` ```python from trustgraph.api import StreamingChunk ``` Clase base para fragmentos de respuesta de transmisión. Se utiliza para operaciones de transmisión basadas en WebSocket, donde las respuestas se entregan de forma incremental a medida que se generan. **Campos:** `content`: `end_of_message`: ### Métodos ### `__init__(self, content: str, end_of_message: bool = False) -> None` Inicializa self. Consulte help(type(self)) para obtener la firma precisa. -- ## `AgentThought` ```python from trustgraph.api import AgentThought ``` Fragmento del razonamiento/proceso de pensamiento del agente. Representa el razonamiento interno o los pasos de planificación del agente durante la ejecución. Estos fragmentos muestran cómo el agente está pensando sobre el problema. **Campos:** `content`: `end_of_message`: `chunk_type`: ### Métodos ### `__init__(self, content: str, end_of_message: bool = False, chunk_type: str = 'thought') -> None` Inicializa self. Consulte help(type(self)) para obtener la firma precisa. -- ## `AgentObservation` ```python from trustgraph.api import AgentObservation ``` Fragmento de observación de la ejecución de la herramienta del agente. Representa el resultado u observación de la ejecución de una herramienta o acción. Estos fragmentos muestran lo que el agente aprendió al usar herramientas. **Campos:** `content`: `end_of_message`: `chunk_type`: ### Métodos ### `__init__(self, content: str, end_of_message: bool = False, chunk_type: str = 'observation') -> None` Inicializa self. Consulte help(type(self)) para obtener la firma precisa. -- ## `AgentAnswer` ```python from trustgraph.api import AgentAnswer ``` Fragmento de la respuesta final del agente. Representa la respuesta final del agente al usuario después de completar su razonamiento y el uso de herramientas. **Atributos:** `chunk_type: Always "final`: answer" **Campos:** `content`: `end_of_message`: `chunk_type`: `end_of_dialog`: ### Métodos ### `__init__(self, content: str, end_of_message: bool = False, chunk_type: str = 'final-answer', end_of_dialog: bool = False) -> None` Inicializa self. Consulte help(type(self)) para obtener la firma precisa. -- ## `RAGChunk` ```python from trustgraph.api import RAGChunk ``` Fragmento de transmisión RAG (Generación Aumentada por Recuperación). Utilizado para transmitir respuestas de RAG de grafos, RAG de documentos, finalización de texto, y otros servicios generativos. **Campos:** `content`: `end_of_message`: `chunk_type`: `end_of_stream`: `error`: typing.Dict[str, str] | None ### Métodos ### `__init__(self, content: str, end_of_message: bool = False, chunk_type: str = 'rag', end_of_stream: bool = False, error: Dict[str, str] | None = None) -> None` Inicializa self. Consulte help(type(self)) para obtener la firma precisa. -- ## `ProvenanceEvent` ```python from trustgraph.api import ProvenanceEvent ``` Evento de procedencia para la explicabilidad. Emitido durante las consultas de GraphRAG cuando el modo de explicabilidad está habilitado. Cada evento representa un nodo de procedencia creado durante el procesamiento de la consulta. **Campos:** `explain_id`: `explain_graph`: `event_type`: ### Métodos ### `__init__(self, explain_id: str, explain_graph: str = '', event_type: str = '') -> None` Inicializar self. Consulte help(type(self)) para obtener la firma precisa. -- ## `ProtocolException` ```python from trustgraph.api import ProtocolException ``` Se genera cuando ocurren errores en el protocolo WebSocket. -- ## `TrustGraphException` ```python from trustgraph.api import TrustGraphException ``` Clase base para todos los errores del servicio TrustGraph. -- ## `AgentError` ```python from trustgraph.api import AgentError ``` Error en el servicio del agente -- ## `ConfigError` ```python from trustgraph.api import ConfigError ``` Error del servicio de configuración -- ## `DocumentRagError` ```python from trustgraph.api import DocumentRagError ``` Error de recuperación de documentos RAG. -- ## `FlowError` ```python from trustgraph.api import FlowError ``` Error de gestión de flujo -- ## `GatewayError` ```python from trustgraph.api import GatewayError ``` Error de la API Gateway -- ## `GraphRagError` ```python from trustgraph.api import GraphRagError ``` Error de recuperación de Graph RAG. -- ## `LLMError` ```python from trustgraph.api import LLMError ``` Error del servicio de modelo de lenguaje grande. -- ## `LoadError` ```python from trustgraph.api import LoadError ``` Error de carga de datos -- ## `LookupError` ```python from trustgraph.api import LookupError ``` Error de búsqueda/consulta -- ## `NLPQueryError` ```python from trustgraph.api import NLPQueryError ``` Error en el servicio de consulta de procesamiento del lenguaje natural. -- ## `RowsQueryError` ```python from trustgraph.api import RowsQueryError ``` Error en el servicio de consulta de filas. -- ## `RequestError` ```python from trustgraph.api import RequestError ``` Error en el procesamiento de la solicitud. -- ## `StructuredQueryError` ```python from trustgraph.api import StructuredQueryError ``` Error en el servicio de consulta estructurada. -- ## `UnexpectedError` ```python from trustgraph.api import UnexpectedError ``` Error inesperado/desconocido -- ## `ApplicationException` ```python from trustgraph.api import ApplicationException ``` Clase base para todos los errores del servicio TrustGraph. --