@muxoai/sdk 1.2.3 → 1.4.2

package/dist/memory-graph.d.ts

@@ -0,0 +1,21 @@
+import type { ConnectionRecord, GovernancePolicy, MemoryKnowledgeGraph, ProvisionedResource, TemporalGraphFact } from "./types.js";
+export interface MemoryGraphInput {
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+        tier: string;
+        policy?: GovernancePolicy;
+    };
+    namespace: string;
+    query?: string;
+    facts: TemporalGraphFact[];
+    resources: Array<Pick<ProvisionedResource, "resourceName" | "status" | "providerName" | "serviceSlug">>;
+    activeConnections: Array<Pick<ConnectionRecord, "id" | "providerSlug" | "providerName" | "createdAt">>;
+    memoriesCount: number;
+}
+/**
+ * Builds the bi-temporal knowledge graph (nodes, active/historical edges, Mermaid preview)
+ * from runtime-agnostic inputs so the Node engine and the Edge Worker render identical graphs.
+ */
+export declare function buildMemoryKnowledgeGraph(input: MemoryGraphInput): MemoryKnowledgeGraph;

package/dist/memory-graph.js

@@ -0,0 +1,173 @@
+import { formatHumanFriendlyExplanation } from "./policy.js";
+/**
+ * Builds the bi-temporal knowledge graph (nodes, active/historical edges, Mermaid preview)
+ * from runtime-agnostic inputs so the Node engine and the Edge Worker render identical graphs.
+ */
+export function buildMemoryKnowledgeGraph(input) {
+    const ws = input.workspace;
+    const query = input.query;
+    const nodeMap = new Map();
+    const rootId = `workspace:${ws.slug}`;
+    nodeMap.set(rootId, {
+        id: rootId,
+        kind: "workspace",
+        label: ws.name,
+        summary: `Workspace ${ws.name} (${ws.slug}, tier=${ws.tier})`,
+        status: "active",
+        metadata: { workspaceId: ws.id, tier: ws.tier },
+    });
+    const ensureNode = (id, status, fallbackKind = "entity", summary) => {
+        const existing = nodeMap.get(id);
+        if (existing) {
+            if (status === "active" && existing.status === "historical") {
+                existing.status = "active";
+            }
+            return existing;
+        }
+        const kind = id.startsWith("workspace:")
+            ? "workspace"
+            : id.startsWith("resource:")
+                ? "resource"
+                : id.startsWith("connection:")
+                    ? "connection"
+                    : id.startsWith("tool:")
+                        ? "tool"
+                        : id.startsWith("guardrail:")
+                            ? "guardrail"
+                            : fallbackKind;
+        const label = id.includes(":")
+            ? id.split(":").slice(1).join(":")
+            : id.length > 36
+                ? `${id.slice(0, 33)}...`
+                : id;
+        const created = {
+            id,
+            kind,
+            label,
+            summary: summary || label,
+            status,
+        };
+        nodeMap.set(id, created);
+        return created;
+    };
+    const edges = input.facts.map((fact) => {
+        const status = fact.validTo === null ? "active" : "historical";
+        const objKind = fact.sourceKind === "preference"
+            ? "preference"
+            : fact.sourceKind === "policy_decision"
+                ? "guardrail"
+                : fact.sourceKind === "resource_topology"
+                    ? "resource"
+                    : "entity";
+        ensureNode(fact.subject, status, "entity", fact.subject);
+        ensureNode(fact.object, status, objKind, fact.summary);
+        return {
+            id: fact.id,
+            source: fact.subject,
+            target: fact.object,
+            subject: fact.subject,
+            object: fact.object,
+            predicate: fact.predicate,
+            summary: fact.summary,
+            confidence: fact.confidence,
+            status,
+            validFrom: fact.validFrom,
+            validTo: fact.validTo,
+            supersededById: fact.supersededById ?? null,
+            sourceKind: fact.sourceKind,
+            sourceReferenceId: fact.sourceReferenceId ?? null,
+        };
+    });
+    for (const res of input.resources) {
+        ensureNode(`resource:${res.resourceName}`, res.status === "active" ? "active" : "historical", "resource", `${res.resourceName} (${res.providerName} / ${res.serviceSlug})`);
+    }
+    for (const conn of input.activeConnections) {
+        const connId = `connection:${conn.providerSlug}`;
+        ensureNode(connId, "active", "connection", `Connected OAuth App: ${conn.providerName} (${conn.providerSlug})`);
+        if (!edges.some((e) => e.source === rootId && e.target === connId)) {
+            edges.push({
+                id: `edge_conn_${conn.id}`,
+                source: rootId,
+                target: connId,
+                predicate: "CONNECTED_TO",
+                summary: `${ws.name} has active OAuth connection to ${conn.providerName}`,
+                confidence: 1.0,
+                status: "active",
+                validFrom: conn.createdAt,
+                validTo: null,
+                supersededById: null,
+                sourceKind: "system",
+                sourceReferenceId: conn.id,
+            });
+        }
+    }
+    const activeEdges = edges.filter((e) => e.status === "active");
+    const historicalEdges = edges.filter((e) => e.status === "historical");
+    const nodes = Array.from(nodeMap.values());
+    const safeMermaidId = (raw, idx) => `N${idx}_${raw.replace(/[^a-zA-Z0-9]/g, "_").slice(0, 14)}`;
+    const nodeIndex = new Map();
+    nodes.slice(0, 24).forEach((n, idx) => {
+        nodeIndex.set(n.id, safeMermaidId(n.label, idx));
+    });
+    const mermaidLines = ["flowchart LR"];
+    for (const n of nodes.slice(0, 24)) {
+        const mId = nodeIndex.get(n.id);
+        const cleanLabel = n.label.replace(/"/g, "'").slice(0, 22);
+        mermaidLines.push(`  ${mId}["${cleanLabel}"]`);
+    }
+    for (const e of edges.slice(0, 24)) {
+        const srcId = nodeIndex.get(e.source);
+        const tgtId = nodeIndex.get(e.target);
+        if (!srcId || !tgtId)
+            continue;
+        const pred = e.predicate.replace(/"/g, "'").slice(0, 18);
+        if (e.status === "active") {
+            mermaidLines.push(`  ${srcId} -->|${pred}| ${tgtId}`);
+        }
+        else {
+            mermaidLines.push(`  ${srcId} -.->|RETIRED: ${pred}| ${tgtId}`);
+        }
+    }
+    const headline = `Bi-Temporal Knowledge Graph (${ws.name}): ${activeEdges.length} active relationship${activeEdges.length === 1 ? "" : "s"}, ${historicalEdges.length} superseded historical relationship${historicalEdges.length === 1 ? "" : "s"} across ${nodes.length} node${nodes.length === 1 ? "" : "s"}.`;
+    const activePreview = activeEdges
+        .slice(0, 4)
+        .map((e) => `${e.source} --[${e.predicate}]--> ${e.target}`)
+        .join("; ");
+    const nonTechnical = [
+        headline,
+        activeEdges.length > 0
+            ? `Current facts: ${activeEdges.slice(0, 3).map((e) => e.summary).join(" · ")}.`
+            : "No active facts recorded yet.",
+        historicalEdges.length > 0
+            ? `Time-travel lineage: ${historicalEdges.length} older fact${historicalEdges.length === 1 ? " was" : "s were"} automatically retired when newer workspace settings or facts replaced them.`
+            : "No superseded historical facts yet.",
+    ].join(" ");
+    const technical = `workspace=${ws.id} | namespace=${input.namespace} | nodes=${nodes.length} | activeEdges=${activeEdges.length} | historicalEdges=${historicalEdges.length} | memories=${input.memoriesCount} | activePreview=[${activePreview || "none"}]`;
+    const explanation = formatHumanFriendlyExplanation({
+        headline,
+        nonTechnical,
+        technical,
+        policy: ws.policy,
+    });
+    return {
+        workspaceId: ws.id,
+        workspaceSlug: ws.slug,
+        namespace: input.namespace,
+        generatedAt: new Date().toISOString(),
+        query: query ?? null,
+        nodes,
+        edges,
+        activeEdges,
+        historicalEdges,
+        stats: {
+            nodesCount: nodes.length,
+            activeEdgesCount: activeEdges.length,
+            historicalEdgesCount: historicalEdges.length,
+            memoriesCount: input.memoriesCount,
+            resourcesCount: input.resources.length,
+            connectionsCount: input.activeConnections.length,
+        },
+        mermaid: mermaidLines.join("\n"),
+        explanation,
+    };
+}

package/dist/nl.d.ts

@@ -0,0 +1,34 @@
+import type { ToolDescriptor } from "./types.js";
+export interface NaturalLanguageResolution {
+    resolved: boolean;
+    tool: ToolDescriptor | null;
+    toolSlug: string | null;
+    input: Record<string, unknown>;
+    extractedInput: Record<string, unknown>;
+    reason: string;
+    confidence: number;
+    resolutionMethod: "exact_slug" | "byok_llm" | "semantic_router";
+    byokUsed: string | null;
+    humanSummary: string;
+    missingInputs: string[];
+    needsConnection: boolean;
+    suggestedByokProvider: string | null;
+    alternatives: Array<{
+        slug: string;
+        name: string;
+        riskLevel: string;
+        creditCost: number;
+    }>;
+}
+export declare function extractParametersFromNaturalLanguage(prompt: string, tool: ToolDescriptor, explicitInput?: Record<string, unknown>): {
+    input: Record<string, unknown>;
+    missingInputs: string[];
+};
+export declare function resolveNaturalLanguageIntent(params: {
+    prompt: string;
+    tools: ToolDescriptor[];
+    explicitInput?: Record<string, unknown>;
+    byokKeys?: Record<string, string>;
+    activeConnectionProviders?: Set<string>;
+    preferByokLlm?: boolean;
+}): Promise<NaturalLanguageResolution>;