@miguelduran14/knowflow 0.1.1

package/dist/explain/openai.js

@@ -0,0 +1,102 @@
+import { readSseStream } from './sse.js';
+/**
+ * Convierte un fallo del gateway en un mensaje accionable. Cubre los tres
+ * modos de fallo típicos de una pasarela corporativa cuyo shape no controlas:
+ * código de error HTTP, respuesta que no es JSON (URL mal, página de login),
+ * y JSON que no sigue el formato OpenAI (falta `choices`).
+ */
+async function readError(response) {
+    const raw = await response.text().catch(() => '');
+    let detail = raw;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.error?.message)
+            detail = parsed.error.message;
+    }
+    catch {
+        // No era JSON.
+    }
+    const hint = response.status === 401 || response.status === 403
+        ? ' — revisa la clave/token y la cabecera de auth.'
+        : response.status === 404
+            ? ' — revisa el endpoint y el nombre del modelo.'
+            : response.status === 429
+                ? ' — límite de tasa o cuota agotada.'
+                : '';
+    return `El endpoint respondió ${response.status}${hint} ${detail.slice(0, 300)}`.trim();
+}
+/**
+ * Adaptador para cualquier API compatible con OpenAI (`/chat/completions`).
+ * Vía "lista para conectar" a una IA corporativa cuyo shape exacto aún no se
+ * conoce: casi todos los gateways (Azure OpenAI, pasarelas internas, la
+ * mayoría de endpoints tipo CODEX/AXET) hablan este formato.
+ *
+ * Mismo contrato BYOK/local-first que el adaptador Claude: la llamada va
+ * directa del navegador del usuario al `endpoint` que él configure. Que ese
+ * endpoint acepte código de clientes es su decisión (restricción de IP).
+ * Si el gateway NO fuese compatible, la interfaz `ExplanationProvider`
+ * permite un adaptador a medida sin tocar el resto del motor.
+ */
+export function createOpenAICompatibleProvider(options) {
+    const authName = options.auth?.name ?? 'Authorization';
+    const authPrefix = options.auth?.prefix ?? 'Bearer ';
+    const maxTokens = options.maxTokens ?? 2000;
+    const headers = () => ({
+        'content-type': 'application/json',
+        [authName]: `${authPrefix}${options.apiKey}`,
+        ...options.headers,
+    });
+    const body = (system, user, stream) => JSON.stringify({
+        model: options.model,
+        max_tokens: maxTokens,
+        messages: [
+            { role: 'system', content: system },
+            { role: 'user', content: user },
+        ],
+        ...(stream ? { stream: true } : {}),
+    });
+    return {
+        id: options.id ?? 'openai-compatible',
+        async complete(system, user) {
+            const response = await fetch(options.endpoint, { method: 'POST', headers: headers(), body: body(system, user, false) });
+            if (!response.ok)
+                throw new Error(await readError(response));
+            const raw = await response.text();
+            let data;
+            try {
+                data = JSON.parse(raw);
+            }
+            catch {
+                throw new Error('El endpoint respondió, pero no en JSON. Revisa que la URL apunte al chat de completions y no a una página de login o a otra ruta.');
+            }
+            if (!Array.isArray(data.choices)) {
+                const why = data.error?.message ? `: ${data.error.message}` : '';
+                throw new Error(`El endpoint respondió pero no en formato compatible con OpenAI (falta "choices")${why}. Confirma que es un endpoint de chat completions.`);
+            }
+            const text = data.choices[0]?.message?.content ?? '';
+            if (text === '')
+                throw new Error('El proveedor devolvió una respuesta vacía');
+            return text;
+        },
+        async stream(system, user, onChunk) {
+            const response = await fetch(options.endpoint, { method: 'POST', headers: headers(), body: body(system, user, true) });
+            if (!response.ok)
+                throw new Error(await readError(response));
+            if (!response.body)
+                throw new Error('El endpoint no devolvió un cuerpo en streaming');
+            let text = '';
+            await readSseStream(response.body, event => {
+                const e = event;
+                const chunk = e.choices?.[0]?.delta?.content;
+                if (chunk) {
+                    text += chunk;
+                    onChunk(chunk);
+                }
+            });
+            if (text === '')
+                throw new Error('El proveedor devolvió una respuesta vacía');
+            return text;
+        },
+    };
+}
+//# sourceMappingURL=openai.js.map

package/dist/explain/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/explain/openai.ts"],"names":[],"mappings":"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"}

package/dist/explain/provider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Interfaz agnóstica de proveedor de explicación (ADR: capa de IA
+ * pluggable, BYOK). El motor no sabe qué proveedor hay detrás; cualquier
+ * implementación que cumpla esto sirve — Claude, OpenAI/GPT, o un fake
+ * para tests.
+ */
+export interface ExplanationProvider {
+    /** Identificador estable del proveedor ('claude', 'fake', …) */
+    readonly id: string;
+    /** Envía system + mensaje de usuario y devuelve el texto de respuesta */
+    complete(system: string, user: string): Promise<string>;
+    /**
+     * Variante en streaming, opcional: emite fragmentos de texto con `onChunk`
+     * a medida que llegan y resuelve con el texto completo. Un proveedor que no
+     * la implemente hace que la capa superior use `complete` (sin token a
+     * token). La salida final es idéntica a la de `complete`.
+     */
+    stream?(system: string, user: string, onChunk: (chunk: string) => void): Promise<string>;
+}

package/dist/explain/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/explain/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/explain/provider.ts"],"names":[],"mappings":""}

package/dist/explain/sse.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lectura de un stream de Server-Sent Events sobre `fetch`. Compartido por
+ * los adaptadores Claude y OpenAI-compatible: ambos entregan la respuesta en
+ * streaming como líneas `data: {json}` separadas por líneas en blanco.
+ * Funciona igual en navegador y en Node 18+ (fetch trae `body` como stream).
+ *
+ * Llama a `onEvent` con el objeto JSON de cada `data:`; ignora `data: [DONE]`
+ * y las líneas que no sean JSON (comentarios `:` de keep-alive, `event:`…).
+ */
+export declare function readSseStream(body: ReadableStream<Uint8Array>, onEvent: (data: unknown) => void): Promise<void>;

package/dist/explain/sse.js

@@ -0,0 +1,44 @@
+/**
+ * Lectura de un stream de Server-Sent Events sobre `fetch`. Compartido por
+ * los adaptadores Claude y OpenAI-compatible: ambos entregan la respuesta en
+ * streaming como líneas `data: {json}` separadas por líneas en blanco.
+ * Funciona igual en navegador y en Node 18+ (fetch trae `body` como stream).
+ *
+ * Llama a `onEvent` con el objeto JSON de cada `data:`; ignora `data: [DONE]`
+ * y las líneas que no sean JSON (comentarios `:` de keep-alive, `event:`…).
+ */
+export async function readSseStream(body, onEvent) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Los eventos SSE terminan en línea en blanco; procesamos por líneas
+            // `data:` sueltas, que es como los emiten estos dos proveedores.
+            let newline;
+            while ((newline = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, newline).trim();
+                buffer = buffer.slice(newline + 1);
+                if (!line.startsWith('data:'))
+                    continue;
+                const payload = line.slice(5).trim();
+                if (payload === '' || payload === '[DONE]')
+                    continue;
+                try {
+                    onEvent(JSON.parse(payload));
+                }
+                catch {
+                    // Fragmento no-JSON (keep-alive u otro): se ignora.
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/explain/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/explain/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAgC,EAChC,OAAgC;IAEhC,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAA;IAC/B,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;IACjC,IAAI,MAAM,GAAG,EAAE,CAAA;IAEf,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;YAC3C,IAAI,IAAI;gBAAE,MAAK;YACf,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;YAEjD,qEAAqE;YACrE,iEAAiE;YACjE,IAAI,OAAe,CAAA;YACnB,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;gBAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAA;gBAC5C,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAA;gBAClC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;oBAAE,SAAQ;gBACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;gBACpC,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,QAAQ;oBAAE,SAAQ;gBACpD,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAA;gBAC9B,CAAC;gBAAC,MAAM,CAAC;oBACP,oDAAoD;gBACtD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,WAAW,EAAE,CAAA;IACtB,CAAC;AACH,CAAC"}

package/dist/flow-parser.d.ts

@@ -0,0 +1,10 @@
+import type { FlowResult } from './types.js';
+/**
+ * Extrae los hechos de flujo de la PROCEDURE DIVISION: párrafos/secciones
+ * en orden de fuente y aristas PERFORM/CALL/GO TO, cada una anclada a la
+ * línea donde aparece. Todo lo no verificable se marca, no se rellena:
+ * un CALL con variable es `dynamic` (el destino real solo se conoce en
+ * ejecución), un destino que no existe en el fuente va a `missingTargets`,
+ * y un fuente sin cabecera PROCEDURE DIVISION queda como `fragment`.
+ */
+export declare function parseFlow(source: string): FlowResult;