trustgraph/docs/tech-specs/python-api-refactor.es.md

---
layout: default
title: "Especificación Técnica de Refactorización de la API de Python"
parent: "Spanish (Beta)"
---

# Especificación Técnica de Refactorización de la API de Python

> **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.

## Resumen

Esta especificación describe una refactorización integral de la biblioteca de cliente de la API de Python de TrustGraph para lograr la paridad de funciones con la API Gateway y agregar soporte para patrones de comunicación en tiempo real modernos.

La refactorización aborda cuatro casos de uso principales:

1. **Interacciones de LLM en Streaming**: Habilitar el streaming en tiempo real de las respuestas de LLM (agente, RAG de grafos, RAG de documentos, finalización de texto, prompts) con una latencia significativamente menor (~60 veces menor, 500 ms frente a 30 s para el primer token).
2. **Operaciones de Datos Masivos**: Soporte para la importación/exportación eficiente de triples, incrustaciones de grafos e incrustaciones de documentos para la gestión de grafos de conocimiento a gran escala.
3. **Paridad de Funciones**: Asegurar que cada punto final de la API Gateway tenga un método de API de Python correspondiente, incluidas las consultas de incrustaciones de grafos.
4. **Conexiones Persistentes**: Habilitar la comunicación basada en WebSocket para solicitudes multiplexadas y una menor sobrecarga de conexión.

## Objetivos

**Paridad de Funciones**: Cada servicio de la API Gateway tiene un método de API de Python correspondiente.
**Soporte de Streaming**: Todos los servicios capaces de streaming (agente, RAG, finalización de texto, prompt) admiten el streaming en la API de Python.
**Transporte WebSocket**: Agregar una capa de transporte WebSocket opcional para conexiones persistentes y multiplexación.
**Operaciones Masivas**: Agregar importación/exportación masiva eficiente para triples, incrustaciones de grafos e incrustaciones de documentos.
**Soporte Completo Async**: Implementación completa de async/await para todas las interfaces (REST, WebSocket, operaciones masivas, métricas).
**Compatibilidad con Versiones Anteriores**: El código existente continúa funcionando sin modificaciones.
**Seguridad de Tipos**: Mantener interfaces con seguridad de tipos utilizando dataclasses y sugerencias de tipo.
**Mejora Progresiva**: El streaming y el async son opcionales a través de la selección explícita de la interfaz.
**Rendimiento**: Lograr una mejora de latencia de 60 veces para las operaciones de streaming.
**Python Moderno**: Soporte para paradigmas tanto síncronos como asíncronos para una máxima flexibilidad.

## Antecedentes

### Estado Actual

La API de Python (`trustgraph-base/trustgraph/api/`) es una biblioteca de cliente REST con los siguientes módulos:

`flow.py`: Gestión de flujos y servicios con ámbito de flujo (50 métodos).
`library.py`: Operaciones de la biblioteca de documentos (9 métodos).
`knowledge.py`: Gestión central de grafos (4 métodos).
`collection.py`: Metadatos de colecciones (3 métodos).
`config.py`: Gestión de configuración (6 métodos).
`types.py`: Definiciones de tipos de datos (5 dataclasses).

**Operaciones Totales**: 50/59 (cobertura del 85%).

### Limitaciones Actuales

**Operaciones Faltantes**:
Consulta de incrustaciones de grafos (búsqueda semántica sobre entidades de grafos).
Importación/exportación masiva para triples, incrustaciones de grafos, incrustaciones de documentos, contextos de entidades, objetos.
Punto final de métricas.

**Capacidades Faltantes**:
Soporte de streaming para servicios de LLM.
Transporte WebSocket.
Solicitudes concurrentes multiplexadas.
Conexiones persistentes.

**Problemas de Rendimiento**:
Alta latencia para las interacciones de LLM (~30 s para el primer token).
Transferencia de datos masiva ineficiente (solicitud REST por elemento).
Sobrecarga de conexión para múltiples operaciones secuenciales.

**Problemas de Experiencia de Usuario**:
Sin retroalimentación en tiempo real durante la generación de LLM.
No se pueden cancelar las operaciones de LLM de larga duración.
Mala escalabilidad para las operaciones masivas.

### Impacto

La mejora de streaming de noviembre de 2024 en la API Gateway proporcionó una mejora de latencia de 60 veces (500 ms frente a 30 s para el primer token) para las interacciones de LLM, pero los usuarios de la API de Python no pueden aprovechar esta capacidad. Esto crea una brecha significativa de experiencia entre los usuarios de Python y los que no lo utilizan.

## Diseño Técnico

### Arquitectura

La API de Python refactorizada utiliza un **enfoque de interfaz modular** con objetos separados para diferentes patrones de comunicación. Todas las interfaces están disponibles tanto en variantes **síncronas como asíncronas**:

1. **Interfaz REST** (existente, mejorada).
   **Sync**: `api.flow()`, `api.library()`, `api.knowledge()`, `api.collection()`, `api.config()`.
   **Async**: `api.async_flow()`.
   Solicitud/respuesta síncrona/asíncrona.
   Modelo de conexión simple.
   Predeterminado para la compatibilidad con versiones anteriores.

2. **Interfaz WebSocket** (nueva).
   **Sync**: `api.socket()`.
   **Async**: `api.async_socket()`.
   Conexión persistente.
   Solicitudes multiplexadas.
   Soporte de streaming.
   Mismas firmas de método que REST donde la funcionalidad se superpone.

3. **Interfaz de Operaciones Masivas** (nueva).
   **Sync**: `api.bulk()`.
   **Async**: `api.async_bulk()`.
   Basado en WebSocket para la eficiencia.
   Importación/exportación basada en iterador/AsyncIterator.
   Maneja conjuntos de datos grandes.

4. **Interfaz de Métricas** (nueva).
   **Sync**: `api.metrics()`.
   **Async**: `api.async_metrics()`.
   Acceso a métricas de Prometheus.

```python
import asyncio

# Synchronous interfaces
api = Api(url="http://localhost:8088/")

# REST (existing, unchanged)
flow = api.flow().id("default")
response = flow.agent(question="...", user="...")

# WebSocket (new)
socket_flow = api.socket().flow("default")
response = socket_flow.agent(question="...", user="...")
for chunk in socket_flow.agent(question="...", user="...", streaming=True):
    print(chunk)

# Bulk operations (new)
bulk = api.bulk()
bulk.import_triples(flow="default", triples=triple_generator())

# Asynchronous interfaces
async def main():
    api = Api(url="http://localhost:8088/")

    # Async REST (new)
    flow = api.async_flow().id("default")
    response = await flow.agent(question="...", user="...")

    # Async WebSocket (new)
    socket_flow = api.async_socket().flow("default")
    async for chunk in socket_flow.agent(question="...", streaming=True):
        print(chunk)

    # Async bulk operations (new)
    bulk = api.async_bulk()
    await bulk.import_triples(flow="default", triples=async_triple_generator())

asyncio.run(main())
```

**Principios clave de diseño:**
**Misma URL para todas las interfaces:** `Api(url="http://localhost:8088/")` funciona para todas.
**Simetría sincrónica/asincrónica:** Cada interfaz tiene variantes tanto sincrónicas como asincrónicas con firmas de método idénticas.
**Firmas idénticas:** Donde la funcionalidad se superpone, las firmas de los métodos son idénticas entre REST y WebSocket, sincrónicas y asincrónicas.
**Mejora progresiva:** Elija la interfaz según las necesidades (REST para tareas simples, WebSocket para transmisión, Bulk para conjuntos de datos grandes, asíncrono para marcos modernos).
**Intención explícita:** `api.socket()` indica WebSocket, `api.async_socket()` indica WebSocket asíncrono.
**Compatible con versiones anteriores:** El código existente no se modifica.

### Componentes

#### 1. Clase API principal (modificada)

Módulo: `trustgraph-base/trustgraph/api/api.py`

**Clase API mejorada:**

```python
class Api:
    def __init__(self, url: str, timeout: int = 60, token: Optional[str] = None):
        self.url = url
        self.timeout = timeout
        self.token = token  # Optional bearer token for REST, query param for WebSocket
        self._socket_client = None
        self._bulk_client = None
        self._async_flow = None
        self._async_socket_client = None
        self._async_bulk_client = None

    # Existing synchronous methods (unchanged)
    def flow(self) -> Flow:
        """Synchronous REST-based flow interface"""
        pass

    def library(self) -> Library:
        """Synchronous REST-based library interface"""
        pass

    def knowledge(self) -> Knowledge:
        """Synchronous REST-based knowledge interface"""
        pass

    def collection(self) -> Collection:
        """Synchronous REST-based collection interface"""
        pass

    def config(self) -> Config:
        """Synchronous REST-based config interface"""
        pass

    # New synchronous methods
    def socket(self) -> SocketClient:
        """Synchronous WebSocket-based interface for streaming operations"""
        if self._socket_client is None:
            self._socket_client = SocketClient(self.url, self.timeout, self.token)
        return self._socket_client

    def bulk(self) -> BulkClient:
        """Synchronous bulk operations interface for import/export"""
        if self._bulk_client is None:
            self._bulk_client = BulkClient(self.url, self.timeout, self.token)
        return self._bulk_client

    def metrics(self) -> Metrics:
        """Synchronous metrics interface"""
        return Metrics(self.url, self.timeout, self.token)

    # New asynchronous methods
    def async_flow(self) -> AsyncFlow:
        """Asynchronous REST-based flow interface"""
        if self._async_flow is None:
            self._async_flow = AsyncFlow(self.url, self.timeout, self.token)
        return self._async_flow

    def async_socket(self) -> AsyncSocketClient:
        """Asynchronous WebSocket-based interface for streaming operations"""
        if self._async_socket_client is None:
            self._async_socket_client = AsyncSocketClient(self.url, self.timeout, self.token)
        return self._async_socket_client

    def async_bulk(self) -> AsyncBulkClient:
        """Asynchronous bulk operations interface for import/export"""
        if self._async_bulk_client is None:
            self._async_bulk_client = AsyncBulkClient(self.url, self.timeout, self.token)
        return self._async_bulk_client

    def async_metrics(self) -> AsyncMetrics:
        """Asynchronous metrics interface"""
        return AsyncMetrics(self.url, self.timeout, self.token)

    # Resource management
    def close(self) -> None:
        """Close all synchronous connections"""
        if self._socket_client:
            self._socket_client.close()
        if self._bulk_client:
            self._bulk_client.close()

    async def aclose(self) -> None:
        """Close all asynchronous connections"""
        if self._async_socket_client:
            await self._async_socket_client.aclose()
        if self._async_bulk_client:
            await self._async_bulk_client.aclose()
        if self._async_flow:
            await self._async_flow.aclose()

    def __enter__(self):
        return self

    def __exit__(self, *args):
        self.close()

    async def __aenter__(self):
        return self

    async def __aexit__(self, *args):
        await self.aclose()
```

#### 2. Cliente WebSocket Síncrono

Módulo: `trustgraph-base/trustgraph/api/socket_client.py` (nuevo)

**Clase SocketClient**:

```python
class SocketClient:
    """Synchronous WebSocket client"""
    def __init__(self, url: str, timeout: int, token: Optional[str]):
        self.url = self._convert_to_ws_url(url)
        self.timeout = timeout
        self.token = token
        self._connection = None
        self._request_counter = 0

    def flow(self, flow_id: str) -> SocketFlowInstance:
        """Get flow instance for WebSocket operations"""
        return SocketFlowInstance(self, flow_id)

    def _connect(self) -> WebSocket:
        """Establish WebSocket connection (lazy)"""
        # Uses asyncio.run() internally to wrap async websockets library
        pass

    def _send_request(
        self,
        service: str,
        flow: Optional[str],
        request: Dict[str, Any],
        streaming: bool = False
    ) -> Union[Dict[str, Any], Iterator[Dict[str, Any]]]:
        """Send request and handle response/streaming"""
        # Synchronous wrapper around async WebSocket calls
        pass

    def close(self) -> None:
        """Close WebSocket connection"""
        pass

class SocketFlowInstance:
    """Synchronous WebSocket flow instance with same interface as REST FlowInstance"""
    def __init__(self, client: SocketClient, flow_id: str):
        self.client = client
        self.flow_id = flow_id

    # Same method signatures as FlowInstance
    def agent(
        self,
        question: str,
        user: str,
        state: Optional[Dict[str, Any]] = None,
        group: Optional[str] = None,
        history: Optional[List[Dict[str, Any]]] = None,
        streaming: bool = False,
        **kwargs
    ) -> Union[Dict[str, Any], Iterator[Dict[str, Any]]]:
        """Agent with optional streaming"""
        pass

    def text_completion(
        self,
        system: str,
        prompt: str,
        streaming: bool = False,
        **kwargs
    ) -> Union[str, Iterator[str]]:
        """Text completion with optional streaming"""
        pass

    # ... similar for graph_rag, document_rag, prompt, etc.
```

**Características principales:**
Conexión perezosa (solo se conecta cuando se envía la primera solicitud)
Multiplexación de solicitudes (hasta 15 concurrentes)
Reconexión automática en caso de desconexión
Análisis de respuesta en streaming
Operación segura para subprocesos
Envoltorio sincrónico alrededor de la biblioteca de websockets asíncrona

#### 3. Cliente WebSocket asíncrono

Módulo: `trustgraph-base/trustgraph/api/async_socket_client.py` (nuevo)

**Clase AsyncSocketClient:**

```python
class AsyncSocketClient:
    """Asynchronous WebSocket client"""
    def __init__(self, url: str, timeout: int, token: Optional[str]):
        self.url = self._convert_to_ws_url(url)
        self.timeout = timeout
        self.token = token
        self._connection = None
        self._request_counter = 0

    def flow(self, flow_id: str) -> AsyncSocketFlowInstance:
        """Get async flow instance for WebSocket operations"""
        return AsyncSocketFlowInstance(self, flow_id)

    async def _connect(self) -> WebSocket:
        """Establish WebSocket connection (lazy)"""
        # Native async websockets library
        pass

    async def _send_request(
        self,
        service: str,
        flow: Optional[str],
        request: Dict[str, Any],
        streaming: bool = False
    ) -> Union[Dict[str, Any], AsyncIterator[Dict[str, Any]]]:
        """Send request and handle response/streaming"""
        pass

    async def aclose(self) -> None:
        """Close WebSocket connection"""
        pass

class AsyncSocketFlowInstance:
    """Asynchronous WebSocket flow instance"""
    def __init__(self, client: AsyncSocketClient, flow_id: str):
        self.client = client
        self.flow_id = flow_id

    # Same method signatures as FlowInstance (but async)
    async def agent(
        self,
        question: str,
        user: str,
        state: Optional[Dict[str, Any]] = None,
        group: Optional[str] = None,
        history: Optional[List[Dict[str, Any]]] = None,
        streaming: bool = False,
        **kwargs
    ) -> Union[Dict[str, Any], AsyncIterator[Dict[str, Any]]]:
        """Agent with optional streaming"""
        pass

    async def text_completion(
        self,
        system: str,
        prompt: str,
        streaming: bool = False,
        **kwargs
    ) -> Union[str, AsyncIterator[str]]:
        """Text completion with optional streaming"""
        pass

    # ... similar for graph_rag, document_rag, prompt, etc.
```

**Características principales**:
Soporte nativo para async/await
Eficiente para aplicaciones asíncronas (FastAPI, aiohttp)
Sin bloqueo de hilos
Misma interfaz que la versión síncrona
AsyncIterator para streaming

#### 4. Cliente de Operaciones Masivas Síncronas

Módulo: `trustgraph-base/trustgraph/api/bulk_client.py` (nuevo)

**Clase BulkClient**:

```python
class BulkClient:
    """Synchronous bulk operations client"""
    def __init__(self, url: str, timeout: int, token: Optional[str]):
        self.url = self._convert_to_ws_url(url)
        self.timeout = timeout
        self.token = token

    def import_triples(
        self,
        flow: str,
        triples: Iterator[Triple],
        **kwargs
    ) -> None:
        """Bulk import triples via WebSocket"""
        pass

    def export_triples(
        self,
        flow: str,
        **kwargs
    ) -> Iterator[Triple]:
        """Bulk export triples via WebSocket"""
        pass

    def import_graph_embeddings(
        self,
        flow: str,
        embeddings: Iterator[Dict[str, Any]],
        **kwargs
    ) -> None:
        """Bulk import graph embeddings via WebSocket"""
        pass

    def export_graph_embeddings(
        self,
        flow: str,
        **kwargs
    ) -> Iterator[Dict[str, Any]]:
        """Bulk export graph embeddings via WebSocket"""
        pass

    # ... similar for document embeddings, entity contexts, objects

    def close(self) -> None:
        """Close connections"""
        pass
```

**Características principales:**
Basado en iteradores para un uso constante de memoria.
Conexiones WebSocket dedicadas por operación.
Seguimiento del progreso (callback opcional).
Manejo de errores con informes de éxito parcial.

#### 5. Cliente de operaciones masivas asíncronas

Módulo: `trustgraph-base/trustgraph/api/async_bulk_client.py` (nuevo)

**Clase AsyncBulkClient:**

```python
class AsyncBulkClient:
    """Asynchronous bulk operations client"""
    def __init__(self, url: str, timeout: int, token: Optional[str]):
        self.url = self._convert_to_ws_url(url)
        self.timeout = timeout
        self.token = token

    async def import_triples(
        self,
        flow: str,
        triples: AsyncIterator[Triple],
        **kwargs
    ) -> None:
        """Bulk import triples via WebSocket"""
        pass

    async def export_triples(
        self,
        flow: str,
        **kwargs
    ) -> AsyncIterator[Triple]:
        """Bulk export triples via WebSocket"""
        pass

    async def import_graph_embeddings(
        self,
        flow: str,
        embeddings: AsyncIterator[Dict[str, Any]],
        **kwargs
    ) -> None:
        """Bulk import graph embeddings via WebSocket"""
        pass

    async def export_graph_embeddings(
        self,
        flow: str,
        **kwargs
    ) -> AsyncIterator[Dict[str, Any]]:
        """Bulk export graph embeddings via WebSocket"""
        pass

    # ... similar for document embeddings, entity contexts, objects

    async def aclose(self) -> None:
        """Close connections"""
        pass
```

**Características principales:**
Basado en AsyncIterator para un uso constante de memoria.
Eficiente para aplicaciones asíncronas.
Soporte nativo para async/await.
Misma interfaz que la versión síncrona.

#### 6. API de flujo REST (Síncrono - Sin cambios)

Módulo: `trustgraph-base/trustgraph/api/flow.py`

La API de flujo REST permanece **completamente sin cambios** para la compatibilidad con versiones anteriores. Todos los métodos existentes siguen funcionando:

`Flow.list()`, `Flow.start()`, `Flow.stop()`, etc.
`FlowInstance.agent()`, `FlowInstance.text_completion()`, `FlowInstance.graph_rag()`, etc.
Todas las firmas y tipos de retorno existentes se conservan.

**Nuevo:** Agregar `graph_embeddings_query()` a REST FlowInstance para la paridad de funciones:

```python
class FlowInstance:
    # All existing methods unchanged...

    # New: Graph embeddings query (REST)
    def graph_embeddings_query(
        self,
        text: str,
        user: str,
        collection: str,
        limit: int = 10,
        **kwargs
    ) -> List[Dict[str, Any]]:
        """Query graph embeddings for semantic search"""
        # Calls POST /api/v1/flow/{flow}/service/graph-embeddings
        pass
```

#### 7. API de flujo REST asíncrono

Módulo: `trustgraph-base/trustgraph/api/async_flow.py` (nuevo)

**Clases AsyncFlow y AsyncFlowInstance:**

```python
class AsyncFlow:
    """Asynchronous REST-based flow interface"""
    def __init__(self, url: str, timeout: int, token: Optional[str]):
        self.url = url
        self.timeout = timeout
        self.token = token

    async def list(self) -> List[Dict[str, Any]]:
        """List all flows"""
        pass

    async def get(self, id: str) -> Dict[str, Any]:
        """Get flow definition"""
        pass

    async def start(self, class_name: str, id: str, description: str, parameters: Dict) -> None:
        """Start a flow"""
        pass

    async def stop(self, id: str) -> None:
        """Stop a flow"""
        pass

    def id(self, flow_id: str) -> AsyncFlowInstance:
        """Get async flow instance"""
        return AsyncFlowInstance(self.url, self.timeout, self.token, flow_id)

    async def aclose(self) -> None:
        """Close connection"""
        pass

class AsyncFlowInstance:
    """Asynchronous REST flow instance"""

    async def agent(
        self,
        question: str,
        user: str,
        state: Optional[Dict[str, Any]] = None,
        group: Optional[str] = None,
        history: Optional[List[Dict[str, Any]]] = None,
        **kwargs
    ) -> Dict[str, Any]:
        """Async agent execution"""
        pass

    async def text_completion(
        self,
        system: str,
        prompt: str,
        **kwargs
    ) -> str:
        """Async text completion"""
        pass

    async def graph_rag(
        self,
        question: str,
        user: str,
        collection: str,
        **kwargs
    ) -> str:
        """Async graph RAG"""
        pass

    # ... all other FlowInstance methods as async versions
```

**Características principales:**
HTTP asíncrono nativo utilizando `aiohttp` o `httpx`
Mismas firmas de método que la API REST sincrónica
Sin transmisión (utilice `async_socket()` para la transmisión)
Eficiente para aplicaciones asíncronas

#### 8. API de métricas

Módulo: `trustgraph-base/trustgraph/api/metrics.py` (nuevo)

**Métricas sincrónicas:**

```python
class Metrics:
    def __init__(self, url: str, timeout: int, token: Optional[str]):
        self.url = url
        self.timeout = timeout
        self.token = token

    def get(self) -> str:
        """Get Prometheus metrics as text"""
        # Call GET /api/metrics
        pass
```

**Métricas Asíncronas**:

```python
class AsyncMetrics:
    def __init__(self, url: str, timeout: int, token: Optional[str]):
        self.url = url
        self.timeout = timeout
        self.token = token

    async def get(self) -> str:
        """Get Prometheus metrics as text"""
        # Call GET /api/metrics
        pass
```

#### 9. Tipos Mejorados

Módulo: `trustgraph-base/trustgraph/api/types.py` (modificado)

**Nuevos Tipos**:

```python
from typing import Iterator, Union, Dict, Any
import dataclasses

@dataclasses.dataclass
class StreamingChunk:
    """Base class for streaming chunks"""
    content: str
    end_of_message: bool = False

@dataclasses.dataclass
class AgentThought(StreamingChunk):
    """Agent reasoning chunk"""
    chunk_type: str = "thought"

@dataclasses.dataclass
class AgentObservation(StreamingChunk):
    """Agent tool observation chunk"""
    chunk_type: str = "observation"

@dataclasses.dataclass
class AgentAnswer(StreamingChunk):
    """Agent final answer chunk"""
    chunk_type: str = "final-answer"
    end_of_dialog: bool = False

@dataclasses.dataclass
class RAGChunk(StreamingChunk):
    """RAG streaming chunk"""
    end_of_stream: bool = False
    error: Optional[Dict[str, str]] = None

# Type aliases for clarity
AgentStream = Iterator[Union[AgentThought, AgentObservation, AgentAnswer]]
RAGStream = Iterator[RAGChunk]
CompletionStream = Iterator[str]
```

#### 6. API de métricas

Módulo: `trustgraph-base/trustgraph/api/metrics.py` (nuevo)

```python
class Metrics:
    def __init__(self, url: str, timeout: int, token: Optional[str]):
        self.url = url
        self.timeout = timeout
        self.token = token

    def get(self) -> str:
        """Get Prometheus metrics as text"""
        # Call GET /api/metrics
        pass
```

### Enfoque de Implementación

#### Fase 1: Mejora del API Central (Semana 1)

1. Agregar métodos `socket()`, `bulk()` y `metrics()` a la clase `Api`
2. Implementar inicialización perezosa para WebSocket y clientes masivos
3. Agregar soporte para administrador de contexto (`__enter__`, `__exit__`)
4. Agregar método `close()` para limpieza
5. Agregar pruebas unitarias para las mejoras del API
6. Verificar compatibilidad con versiones anteriores

**Compatibilidad con versiones anteriores**: No hay cambios que rompan la compatibilidad. Solo se agregan nuevos métodos.

#### Fase 2: Cliente WebSocket (Semanas 2-3)

1. Implementar clase `SocketClient` con gestión de conexión
2. Implementar `SocketFlowInstance` con las mismas firmas de método que `FlowInstance`
3. Agregar soporte para multiplexación de solicitudes (hasta 15 concurrentes)
4. Agregar análisis de respuesta en streaming para diferentes tipos de fragmentos
5. Agregar lógica de reconexión automática
6. Agregar pruebas unitarias e integrales
7. Documentar patrones de uso de WebSocket

**Compatibilidad con versiones anteriores**: Nueva interfaz solamente. No tiene impacto en el código existente.

#### Fase 3: Soporte de Streaming (Semanas 3-4)

1. Agregar clases de tipo de fragmento de streaming (`AgentThought`, `AgentObservation`, `AgentAnswer`, `RAGChunk`)
2. Implementar análisis de respuesta en streaming en `SocketClient`
3. Agregar parámetro de streaming a todos los métodos LLM en `SocketFlowInstance`
4. Manejar casos de error durante el streaming
5. Agregar pruebas unitarias e integrales para el streaming
6. Agregar ejemplos de streaming a la documentación

**Compatibilidad con versiones anteriores**: Nueva interfaz solamente. El API REST existente no se modifica.

#### Fase 4: Operaciones Masivas (Semanas 4-5)

1. Implementar clase `BulkClient`
2. Agregar métodos de importación/exportación masiva para triples, incrustaciones, contextos, objetos
3. Implementar procesamiento basado en iterador para un uso constante de memoria
4. Agregar seguimiento de progreso (callback opcional)
5. Agregar manejo de errores con informes de éxito parcial
6. Agregar pruebas unitarias e integrales
7. Agregar ejemplos de operaciones masivas

**Compatibilidad con versiones anteriores**: Nueva interfaz solamente. No tiene impacto en el código existente.

#### Fase 5: Paridad de Funciones y Pulido (Semana 5)

1. Agregar `graph_embeddings_query()` a REST `FlowInstance`
2. Implementar clase `Metrics`
3. Agregar pruebas de integración exhaustivas
4. Pruebas de rendimiento
5. Actualizar toda la documentación
6. Crear una guía de migración

**Compatibilidad con versiones anteriores**: Nuevos métodos solamente. No tiene impacto en el código existente.

### Modelos de Datos

#### Selección de Interfaz

```python
# Single API instance, same URL for all interfaces
api = Api(url="http://localhost:8088/")

# Synchronous interfaces
rest_flow = api.flow().id("default")           # Sync REST
socket_flow = api.socket().flow("default")     # Sync WebSocket
bulk = api.bulk()                               # Sync bulk operations
metrics = api.metrics()                         # Sync metrics

# Asynchronous interfaces
async_rest_flow = api.async_flow().id("default")      # Async REST
async_socket_flow = api.async_socket().flow("default") # Async WebSocket
async_bulk = api.async_bulk()                          # Async bulk operations
async_metrics = api.async_metrics()                    # Async metrics
```

#### Tipos de respuesta de transmisión

**Transmisión del agente**:

```python
api = Api(url="http://localhost:8088/")

# REST interface - non-streaming (existing)
rest_flow = api.flow().id("default")
response = rest_flow.agent(question="What is ML?", user="user123")
print(response["response"])

# WebSocket interface - non-streaming (same signature)
socket_flow = api.socket().flow("default")
response = socket_flow.agent(question="What is ML?", user="user123")
print(response["response"])

# WebSocket interface - streaming (new)
for chunk in socket_flow.agent(question="What is ML?", user="user123", streaming=True):
    if isinstance(chunk, AgentThought):
        print(f"Thinking: {chunk.content}")
    elif isinstance(chunk, AgentObservation):
        print(f"Observed: {chunk.content}")
    elif isinstance(chunk, AgentAnswer):
        print(f"Answer: {chunk.content}")
        if chunk.end_of_dialog:
            break
```

**Transmisión RAG**:

```python
api = Api(url="http://localhost:8088/")

# REST interface - non-streaming (existing)
rest_flow = api.flow().id("default")
response = rest_flow.graph_rag(question="What is Python?", user="user123", collection="default")
print(response)

# WebSocket interface - streaming (new)
socket_flow = api.socket().flow("default")
for chunk in socket_flow.graph_rag(
    question="What is Python?",
    user="user123",
    collection="default",
    streaming=True
):
    print(chunk.content, end="", flush=True)
    if chunk.end_of_stream:
        break
```

**Operaciones masivas (síncronas):**

```python
api = Api(url="http://localhost:8088/")

# Bulk import triples
def triple_generator():
    yield Triple(s="http://ex.com/alice", p="http://ex.com/type", o="Person")
    yield Triple(s="http://ex.com/alice", p="http://ex.com/name", o="Alice")
    yield Triple(s="http://ex.com/bob", p="http://ex.com/type", o="Person")

bulk = api.bulk()
bulk.import_triples(flow="default", triples=triple_generator())

# Bulk export triples
for triple in bulk.export_triples(flow="default"):
    print(f"{triple.s} -> {triple.p} -> {triple.o}")
```

**Operaciones masivas (asíncronas):**

```python
import asyncio

async def main():
    api = Api(url="http://localhost:8088/")

    # Async bulk import triples
    async def async_triple_generator():
        yield Triple(s="http://ex.com/alice", p="http://ex.com/type", o="Person")
        yield Triple(s="http://ex.com/alice", p="http://ex.com/name", o="Alice")
        yield Triple(s="http://ex.com/bob", p="http://ex.com/type", o="Person")

    bulk = api.async_bulk()
    await bulk.import_triples(flow="default", triples=async_triple_generator())

    # Async bulk export triples
    async for triple in bulk.export_triples(flow="default"):
        print(f"{triple.s} -> {triple.p} -> {triple.o}")

asyncio.run(main())
```

**Ejemplo de REST asíncrono**:

```python
import asyncio

async def main():
    api = Api(url="http://localhost:8088/")

    # Async REST flow operations
    flow = api.async_flow().id("default")
    response = await flow.agent(question="What is ML?", user="user123")
    print(response["response"])

asyncio.run(main())
```

**Ejemplo de transmisión WebSocket asíncrona:**

```python
import asyncio

async def main():
    api = Api(url="http://localhost:8088/")

    # Async WebSocket streaming
    socket = api.async_socket()
    flow = socket.flow("default")

    async for chunk in flow.agent(question="What is ML?", user="user123", streaming=True):
        if isinstance(chunk, AgentAnswer):
            print(chunk.content, end="", flush=True)
            if chunk.end_of_dialog:
                break

asyncio.run(main())
```

### APIs

#### New APIs

1. **Clase API Core**:
   **Síncrono**:
     `Api.socket()` - Obtener cliente WebSocket síncrono
     `Api.bulk()` - Obtener cliente de operaciones masivas síncrono
     `Api.metrics()` - Obtener cliente de métricas síncrono
     `Api.close()` - Cerrar todas las conexiones síncronas
     Soporte de administrador de contexto (`__enter__`, `__exit__`)
   **Asíncrono**:
     `Api.async_flow()` - Obtener cliente de flujo REST asíncrono
     `Api.async_socket()` - Obtener cliente WebSocket asíncrono
     `Api.async_bulk()` - Obtener cliente de operaciones masivas asíncrono
     `Api.async_metrics()` - Obtener cliente de métricas asíncrono
     `Api.aclose()` - Cerrar todas las conexiones asíncronas
     Soporte de administrador de contexto asíncrono (`__aenter__`, `__aexit__`)

2. **Cliente WebSocket Síncrono**:
   `SocketClient.flow(flow_id)` - Obtener instancia de flujo WebSocket
   `SocketFlowInstance.agent(..., streaming: bool = False)` - Agente con transmisión opcional
   `SocketFlowInstance.text_completion(..., streaming: bool = False)` - Completar texto con transmisión opcional
   `SocketFlowInstance.graph_rag(..., streaming: bool = False)` - RAG de gráfico con transmisión opcional
   `SocketFlowInstance.document_rag(..., streaming: bool = False)` - RAG de documento con transmisión opcional
   `SocketFlowInstance.prompt(..., streaming: bool = False)` - Prompt con transmisión opcional
   `SocketFlowInstance.graph_embeddings_query()` - Consulta de incrustaciones de gráfico
   Todos los demás métodos de FlowInstance con firmas idénticas

3. **Cliente WebSocket Asíncrono**:
   `AsyncSocketClient.flow(flow_id)` - Obtener instancia de flujo WebSocket asíncrono
   `AsyncSocketFlowInstance.agent(..., streaming: bool = False)` - Agente asíncrono con transmisión opcional
   `AsyncSocketFlowInstance.text_completion(..., streaming: bool = False)` - Completar texto asíncrono con transmisión opcional
   `AsyncSocketFlowInstance.graph_rag(..., streaming: bool = False)` - RAG de gráfico asíncrono con transmisión opcional
   `AsyncSocketFlowInstance.document_rag(..., streaming: bool = False)` - RAG de documento asíncrono con transmisión opcional
   `AsyncSocketFlowInstance.prompt(..., streaming: bool = False)` - Prompt asíncrono con transmisión opcional
   `AsyncSocketFlowInstance.graph_embeddings_query()` - Consulta de incrustaciones de gráfico asíncrona
   Todos los demás métodos de FlowInstance como versiones asíncronas

4. **Cliente de Operaciones Masivas Síncrono**:
   `BulkClient.import_triples(flow, triples)` - Importación masiva de triples
   `BulkClient.export_triples(flow)` - Exportación masiva de triples
   `BulkClient.import_graph_embeddings(flow, embeddings)` - Importación masiva de incrustaciones de gráfico
   `BulkClient.export_graph_embeddings(flow)` - Exportación masiva de incrustaciones de gráfico
   `BulkClient.import_document_embeddings(flow, embeddings)` - Importación masiva de incrustaciones de documento
   `BulkClient.export_document_embeddings(flow)` - Exportación masiva de incrustaciones de documento
   `BulkClient.import_entity_contexts(flow, contexts)` - Importación masiva de contextos de entidades
   `BulkClient.export_entity_contexts(flow)` - Exportación masiva de contextos de entidades
   `BulkClient.import_objects(flow, objects)` - Importación masiva de objetos

5. **Cliente de Operaciones Masivas Asíncrono**:
   `AsyncBulkClient.import_triples(flow, triples)` - Importación asíncrona masiva de triples
   `AsyncBulkClient.export_triples(flow)` - Exportación asíncrona masiva de triples
   `AsyncBulkClient.import_graph_embeddings(flow, embeddings)` - Importación asíncrona masiva de incrustaciones de gráfico
   `AsyncBulkClient.export_graph_embeddings(flow)` - Exportación asíncrona masiva de incrustaciones de gráfico
   `AsyncBulkClient.import_document_embeddings(flow, embeddings)` - Importación asíncrona masiva de incrustaciones de documento
   `AsyncBulkClient.export_document_embeddings(flow)` - Exportación asíncrona masiva de incrustaciones de documento
   `AsyncBulkClient.import_entity_contexts(flow, contexts)` - Importación asíncrona masiva de contextos de entidades
   `AsyncBulkClient.export_entity_contexts(flow)` - Exportación asíncrona masiva de contextos de entidades
   `AsyncBulkClient.import_objects(flow, objects)` - Importación asíncrona masiva de objetos

6. **Cliente de Flujo REST Asíncrono**:
   `AsyncFlow.list()` - Listar todos los flujos de forma asíncrona
   `AsyncFlow.get(id)` - Obtener definición de flujo de forma asíncrona
   `AsyncFlow.start(...)` - Iniciar flujo de forma asíncrona
   `AsyncFlow.stop(id)` - Detener flujo de forma asíncrona
   `AsyncFlow.id(flow_id)` - Obtener instancia de flujo de forma asíncrona
   `AsyncFlowInstance.agent(...)` - Ejecución de agente asíncrona
   `AsyncFlowInstance.text_completion(...)` - Completar texto de forma asíncrona
   `AsyncFlowInstance.graph_rag(...)` - RAG de gráfico asíncrono
   Todos los demás métodos de FlowInstance como versiones asíncronas

7. **Clientes de Métricas**:
   `Metrics.get()` - Métricas de Prometheus síncronas
   `AsyncMetrics.get()` - Métricas de Prometheus asíncronas

8. **Mejora de la API REST de Flujo**:
   `FlowInstance.graph_embeddings_query()` - Consulta de incrustaciones de gráfico (paridad de funciones síncronas)
   `AsyncFlowInstance.graph_embeddings_query()` - Consulta de incrustaciones de gráfico (paridad de funciones asíncronas)

#### APIs Modificadas

1. **Constructor** (pequeña mejora):
   ```python
   Api(url: str, timeout: int = 60, token: Optional[str] = None)
   ```
   Se agregó el parámetro `token` (opcional, para autenticación).
   Si `None` no se especifica (por defecto): No se utiliza autenticación.
   Si se especifica: Se utiliza como token de tipo "bearer" para REST (`Authorization: Bearer <token>`), parámetro de consulta para WebSocket (`?token=<token>`).
   No se realizaron otros cambios; es totalmente compatible con versiones anteriores.

2. **Sin cambios que rompan la compatibilidad**:
   Todos los métodos de la API REST existentes no se han modificado.
   Todas las firmas existentes se han conservado.
   Todos los tipos de retorno existentes se han conservado.

### Detalles de implementación

#### Manejo de errores

**Errores de conexión WebSocket**:
```python
try:
    api = Api(url="http://localhost:8088/")
    socket = api.socket()
    socket_flow = socket.flow("default")
    response = socket_flow.agent(question="...", user="user123")
except ConnectionError as e:
    print(f"WebSocket connection failed: {e}")
    print("Hint: Ensure Gateway is running and WebSocket endpoint is accessible")
```

**Respaldo Elegante**:
```python
api = Api(url="http://localhost:8088/")

try:
    # Try WebSocket streaming first
    socket_flow = api.socket().flow("default")
    for chunk in socket_flow.agent(question="...", user="...", streaming=True):
        print(chunk.content)
except ConnectionError:
    # Fall back to REST non-streaming
    print("WebSocket unavailable, falling back to REST")
    rest_flow = api.flow().id("default")
    response = rest_flow.agent(question="...", user="...")
    print(response["response"])
```

**Errores de transmisión parcial**:
```python
api = Api(url="http://localhost:8088/")
socket_flow = api.socket().flow("default")

accumulated = []
try:
    for chunk in socket_flow.graph_rag(question="...", streaming=True):
        accumulated.append(chunk.content)
        if chunk.error:
            print(f"Error occurred: {chunk.error}")
            print(f"Partial response: {''.join(accumulated)}")
            break
except Exception as e:
    print(f"Streaming error: {e}")
    print(f"Partial response: {''.join(accumulated)}")
```

#### Gestión de Recursos

**Soporte para Administradores de Contexto**:
```python
# Automatic cleanup
with Api(url="http://localhost:8088/") as api:
    socket_flow = api.socket().flow("default")
    response = socket_flow.agent(question="...", user="user123")
# All connections automatically closed

# Manual cleanup
api = Api(url="http://localhost:8088/")
try:
    socket_flow = api.socket().flow("default")
    response = socket_flow.agent(question="...", user="user123")
finally:
    api.close()  # Explicitly close all connections (WebSocket, bulk, etc.)
```

#### Concurrencia y Subprocesamiento

**Seguridad de Subprocesos**:
Cada instancia de `Api` mantiene su propia conexión.
El transporte WebSocket utiliza bloqueos para el multiplexado de solicitudes, que es seguro para subprocesos.
Múltiples subprocesos pueden compartir una instancia de `Api` de forma segura.
Los iteradores de transmisión no son seguros para subprocesos (se deben consumir desde un solo subproceso).

**Soporte Asíncrono** (consideración futura):
```python
# Phase 2 enhancement (not in initial scope)
import asyncio

async def main():
    api = await AsyncApi(url="ws://localhost:8088/")
    flow = api.flow().id("default")

    async for chunk in flow.agent(question="...", streaming=True):
        print(chunk.content)

    await api.close()

asyncio.run(main())
```

## Consideraciones de seguridad

### Autenticación

**Parámetro de token**:
```python
# No authentication (default)
api = Api(url="http://localhost:8088/")

# With authentication
api = Api(url="http://localhost:8088/", token="mytoken")
```

**Transporte REST**:
Token del portador a través del encabezado `Authorization`
Se aplica automáticamente a todas las solicitudes REST
Formato: `Authorization: Bearer <token>`

**Transporte WebSocket**:
Token a través de un parámetro de consulta adjunto a la URL de WebSocket
Se aplica automáticamente durante el establecimiento de la conexión
Formato: `ws://localhost:8088/api/v1/socket?token=<token>`

**Implementación**:
```python
class SocketClient:
    def _connect(self) -> WebSocket:
        # Construct WebSocket URL with optional token
        ws_url = f"{self.url}/api/v1/socket"
        if self.token:
            ws_url = f"{ws_url}?token={self.token}"
        # Connect to WebSocket
        return websocket.connect(ws_url)
```

**Ejemplo:**
```python
# REST with auth
api = Api(url="http://localhost:8088/", token="mytoken")
flow = api.flow().id("default")
# All REST calls include: Authorization: Bearer mytoken

# WebSocket with auth
socket = api.socket()
# Connects to: ws://localhost:8088/api/v1/socket?token=mytoken
```

### Comunicación Segura

Soporta tanto los esquemas WS (WebSocket) como los de WSS (WebSocket Secure).
Validación de certificados TLS para conexiones WSS.
Verificación de certificados opcional para desarrollo (con advertencia).

### Validación de Datos de Entrada

Validar esquemas de URL (http, https, ws, wss).
Validar valores de parámetros de transporte.
Validar combinaciones de parámetros de transmisión.
Validar tipos de datos para la importación masiva.

## Consideraciones de Rendimiento

### Mejoras en la Latencia

**Operaciones de LLM en Transmisión**:
**Tiempo hasta el primer token**: ~500ms (vs ~30s sin transmisión)
**Mejora**: 60 veces más rápido en términos de rendimiento percibido.
**Aplicable a**: Agente, Graph RAG, Document RAG, Completar Texto, Prompt.

**Conexiones Persistentes**:
**Sobrecarga de la conexión**: Eliminada para solicitudes posteriores.
**Handshake de WebSocket**: Costo único (~100ms).
**Aplicable a**: Todas las operaciones al usar el transporte WebSocket.

### Mejoras en el Rendimiento (Throughput)

**Operaciones Masivas**:
**Importación de triples**: ~10,000 triples/segundo (vs ~100/segundo con REST por elemento).
**Importación de embeddings**: ~5,000 embeddings/segundo (vs ~50/segundo con REST por elemento).
**Mejora**: 100 veces más de rendimiento para operaciones masivas.

**Multiplexación de Solicitudes**:
**Solicitudes concurrentes**: Hasta 15 solicitudes simultáneas sobre una sola conexión.
**Reutilización de la conexión**: Sin sobrecarga de conexión para operaciones concurrentes.

### Consideraciones de Memoria

**Respuestas en Transmisión**:
Uso constante de memoria (procesa los fragmentos a medida que llegan).
No se almacena en búfer la respuesta completa.
Adecuado para salidas muy largas (>1MB).

**Operaciones Masivas**:
Procesamiento basado en iteradores (uso constante de memoria).
No se carga todo el conjunto de datos en la memoria.
Adecuado para conjuntos de datos con millones de elementos.

### Pruebas de Rendimiento (Esperadas)

| Operación | REST (existente) | WebSocket (en transmisión) | Mejora |
|-----------|----------------|----------------------|-------------|
| Agente (tiempo hasta el primer token) | 30s | 0.5s | 60x |
| Graph RAG (tiempo hasta el primer token) | 25s | 0.5s | 50x |
| Importar 10K triples | 100s | 1s | 100x |
| Importar 1M triples | 10,000s (2.7h) | 100s (1.6m) | 100x |
| 10 solicitudes pequeñas concurrentes | 5s (secuencial) | 0.5s (paralelo) | 10x |

## Estrategia de Pruebas

### Pruebas Unitarias

**Capa de Transporte** (`test_transport.py`):
Probar la solicitud/respuesta de transporte REST
Probar la conexión de transporte WebSocket
Probar la reconexión de transporte WebSocket
Probar el multiplexado de solicitudes
Probar el análisis de la respuesta de transmisión
Simular un servidor WebSocket para pruebas deterministas

**Métodos de la API** (`test_flow.py`, `test_library.py`, etc.):
Probar nuevos métodos con transporte simulado
Probar el manejo de parámetros de transmisión
Probar iteradores de operaciones masivas
Probar el manejo de errores

**Tipos** (`test_types.py`):
Probar nuevos tipos de fragmentos de transmisión
Probar la serialización/deserialización de tipos

### Pruebas de Integración

**REST de Extremo a Extremo** (`test_integration_rest.py`):
Probar todas las operaciones contra la puerta de enlace real (modo REST)
Verificar la compatibilidad con versiones anteriores
Probar condiciones de error

**WebSocket de Extremo a Extremo** (`test_integration_websocket.py`):
Probar todas las operaciones contra la puerta de enlace real (modo WebSocket)
Probar operaciones de transmisión
Probar operaciones masivas
Probar solicitudes concurrentes
Probar la recuperación de la conexión

**Servicios de Transmisión** (`test_streaming_integration.py`):
Probar la transmisión de agentes (pensamientos, observaciones, respuestas)
Probar la transmisión de RAG (fragmentos incrementales)
Probar la transmisión de finalización de texto (token por token)
Probar la transmisión de indicaciones
Probar el manejo de errores durante la transmisión

**Operaciones Masivas** (`test_bulk_integration.py`):
Probar la importación/exportación masiva de triples (1K, 10K, 100K elementos)
Probar la importación/exportación masiva de incrustaciones
Probar el uso de memoria durante las operaciones masivas
Probar el seguimiento del progreso

### Pruebas de Rendimiento

**Mediciones de Latencia** (`test_performance_latency.py`):
Medir el tiempo hasta el primer token (transmisión vs. no transmisión)
Medir la sobrecarga de la conexión (REST vs WebSocket)
Comparar con puntos de referencia esperados

**Mediciones de Rendimiento** (`test_performance_throughput.py`):
Medir el rendimiento de la importación masiva
Medir la eficiencia del multiplexado de solicitudes
Comparar con puntos de referencia esperados

### Pruebas de Compatibilidad

**Compatibilidad con Versiones Anteriores** (`test_backward_compatibility.py`):
Ejecutar el conjunto de pruebas existente contra la API refactorizada
Verificar la ausencia de cambios que rompan la compatibilidad
Probar la ruta de migración para patrones comunes

## Plan de Migración

### Fase 1: Migración Transparente (Predeterminada)

**No se requieren cambios en el código**. El código existente continúa funcionando:

```python
# Existing code works unchanged
api = Api(url="http://localhost:8088/")
flow = api.flow().id("default")
response = flow.agent(question="What is ML?", user="user123")
```

### Fase 2: Transmisión por demanda (Simple)

**Utilice la interfaz `api.socket()`** para habilitar la transmisión:

```python
# Before: Non-streaming REST
api = Api(url="http://localhost:8088/")
rest_flow = api.flow().id("default")
response = rest_flow.agent(question="What is ML?", user="user123")
print(response["response"])

# After: Streaming WebSocket (same parameters!)
api = Api(url="http://localhost:8088/")  # Same URL
socket_flow = api.socket().flow("default")

for chunk in socket_flow.agent(question="What is ML?", user="user123", streaming=True):
    if isinstance(chunk, AgentAnswer):
        print(chunk.content, end="", flush=True)
```

**Puntos clave:**
La misma URL para REST y WebSocket.
Las mismas firmas de métodos (migración sencilla).
Simplemente agregue `.socket()` y `streaming=True`.

### Fase 3: Operaciones masivas (Nueva funcionalidad)

**Utilice la interfaz `api.bulk()`** para conjuntos de datos grandes:

```python
# Before: Inefficient per-item operations
api = Api(url="http://localhost:8088/")
flow = api.flow().id("default")

for triple in my_large_triple_list:
    # Slow per-item operations
    # (no direct bulk insert in REST API)
    pass

# After: Efficient bulk loading
api = Api(url="http://localhost:8088/")  # Same URL
bulk = api.bulk()

# This is fast (10,000 triples/second)
bulk.import_triples(flow="default", triples=iter(my_large_triple_list))
```

### Actualizaciones de la documentación

1. **README.md**: Agregar ejemplos de transmisión y WebSocket
2. **Referencia de la API**: Documentar todos los nuevos métodos y parámetros
3. **Guía de migración**: Guía paso a paso para habilitar la transmisión
4. **Ejemplos**: Agregar scripts de ejemplo para patrones comunes
5. **Guía de rendimiento**: Documentar las mejoras de rendimiento esperadas

### Política de obsolescencia

**No hay obsolescencias**. Todas las API existentes siguen siendo compatibles. Esto es una mejora pura.

## Cronograma

### Semana 1: Base
Capa de abstracción de transporte
Refactorizar código REST existente
Pruebas unitarias para la capa de transporte
Verificación de compatibilidad con versiones anteriores

### Semana 2: Transporte WebSocket
Implementación del transporte WebSocket
Gestión de conexiones y reconexión
Multiplexación de solicitudes
Pruebas unitarias e de integración

### Semana 3: Soporte de transmisión
Agregar parámetro de transmisión a los métodos de LLM
Implementar el análisis de respuestas de transmisión
Agregar tipos de fragmentos de transmisión
Pruebas de integración de transmisión

### Semana 4: Operaciones masivas
Agregar métodos de importación/exportación masivos
Implementar operaciones basadas en iteradores
Pruebas de rendimiento
Pruebas de integración de operaciones masivas

### Semana 5: Paridad de funciones y documentación
Agregar consulta de incrustaciones de grafos
Agregar API de métricas
Documentación completa
Guía de migración
Versión candidata

### Semana 6: Lanzamiento
Pruebas de integración finales
Pruebas de referencia de rendimiento
Documentación de lanzamiento
Anuncio a la comunidad

**Duración total**: 6 semanas

## Preguntas abiertas

### Preguntas de diseño de la API

1. **Soporte asíncrono**: ✅ **RESUELTO** - Soporte asíncrono completo incluido en el lanzamiento inicial
   Todas las interfaces tienen variantes asíncronas: `async_flow()`, `async_socket()`, `async_bulk()`, `async_metrics()`
   Proporciona una simetría completa entre las API sincrónicas y asíncronas
   Esencial para marcos de trabajo asíncronos modernos (FastAPI, aiohttp)

2. **Seguimiento del progreso**: ¿Deben las operaciones masivas admitir devoluciones de llamada de progreso?
   ```python
   def progress_callback(processed: int, total: Optional[int]):
       print(f"Processed {processed} items")

   bulk.import_triples(flow="default", triples=triples, on_progress=progress_callback)
   ```
   **Recomendación**: Agregar en la Fase 2. No es crítico para la versión inicial.

3. **Tiempo de espera de la transmisión**: ¿Cómo debemos manejar los tiempos de espera para las operaciones de transmisión?
   **Recomendación**: Utilizar el mismo tiempo de espera que para las operaciones no de transmisión, pero restablecerlo cada vez que se recibe un fragmento.

4. **Almacenamiento en búfer de fragmentos**: ¿Debemos almacenar los fragmentos en búfer o devolverlos inmediatamente?
   **Recomendación**: Devolverlos inmediatamente para lograr la menor latencia.

5. **Servicios globales a través de WebSocket**: ¿Debería `api.socket()` admitir servicios globales (biblioteca, conocimiento, colección, configuración) o solo servicios específicos del flujo?
   **Recomendación**: Comenzar solo con servicios específicos del flujo (donde la transmisión es importante). Agregar servicios globales si es necesario en la Fase 2.

### Preguntas de implementación

1. **Biblioteca de WebSocket**: ¿Debemos usar `websockets`, `websocket-client` o `aiohttp`?
   **Recomendación**: `websockets` (asíncrono, maduro, bien mantenido). Envolverlo en una interfaz síncrona utilizando `asyncio.run()`.

2. **Grupo de conexiones**: ¿Debemos admitir múltiples instancias concurrentes de `Api` que compartan un grupo de conexiones?
   **Recomendación**: Dejar para la Fase 2. Cada instancia de `Api` tendrá sus propias conexiones inicialmente.

3. **Reutilización de conexiones**: ¿Deben `SocketClient` y `BulkClient` compartir la misma conexión de WebSocket, o usar conexiones separadas?
   **Recomendación**: Conexiones separadas. Implementación más sencilla, separación de responsabilidades más clara.

4. **Conexión perezosa vs. activa**: ¿Se debe establecer la conexión de WebSocket en `api.socket()` o en la primera solicitud?
   **Recomendación**: Perezosa (en la primera solicitud). Evita la sobrecarga de la conexión si el usuario solo utiliza métodos REST.

### Preguntas de prueba

1. **Pasarela de simulación**: ¿Debemos crear una pasarela de simulación ligera para las pruebas, o probar contra la pasarela real?
   **Recomendación**: Ambos. Utilizar simulaciones para pruebas unitarias, y la pasarela real para pruebas de integración.

2. **Pruebas de regresión de rendimiento**: ¿Debemos agregar pruebas de regresión de rendimiento automatizadas a CI?
   **Recomendación**: Sí, pero con umbrales amplios para tener en cuenta la variabilidad del entorno de CI.

## Referencias

### Especificaciones técnicas relacionadas
`docs/tech-specs/streaming-llm-responses.md` - Implementación de transmisión en la pasarela
`docs/tech-specs/rag-streaming-support.md` - Soporte de transmisión RAG

### Archivos de implementación
`trustgraph-base/trustgraph/api/` - Código fuente de la API de Python
`trustgraph-flow/trustgraph/gateway/` - Código fuente de la pasarela
`trustgraph-flow/trustgraph/gateway/dispatch/mux.py` - Implementación de referencia de multiplexor de WebSocket

### Documentación
`docs/apiSpecification.md` - Referencia completa de la API
`docs/api-status-summary.md` - Resumen del estado de la API
`README.websocket` - Documentación del protocolo WebSocket
`STREAMING-IMPLEMENTATION-NOTES.txt` - Notas de implementación de transmisión

### Bibliotecas externas
`websockets` - Biblioteca de WebSocket de Python (https://websockets.readthedocs.io/)
`requests` - Biblioteca HTTP de Python (existente)