​

UOM Assistant Frontend: State Synchronization & LangGraph Runtime

​

1. The Runtime Wrapper & Local State Machine

• File Path: frontend/uom-translator-ui/components/assistant-ui/runtime/assistant-runtime-provider.tsx
• Component: AssistantRuntimeProviderWrapper

• graphState: A Partial<BackendState> containing the active translation data, validation errors, and equivalence diff logs.
• error and runError: Diagnostic models logging compilation failures and stream aborted triggers.
• activeNode: Identifies the current executing python node in the backend (e.g., input extraction, schema inspection, compilation validation, equivalence checks, and evaluations).

​

2. Configurable Context Injection (stream)

const savedConfig = typeof window !== "undefined" ? localStorage.getItem("uom_translator_config") : null;
const configurable: UomConfig = savedConfig ? JSON.parse(savedConfig) : {};

const payload = {
    input: messages.length ? { messages } : null,
    // "updates" is required for human-in-the-loop: @assistant-ui/react-langgraph only
    // captures LangGraph's native `interrupt()` payload from `updates` events (it reads
    // `chunk.data.__interrupt__`). Without it the suspension is never surfaced live.
    streamMode: ["messages-tuple", "updates", "values", "custom"],
    streamSubgraphs: true,
    ...(config.abortSignal != null && { signal: config.abortSignal }),
    onDisconnect: "cancel",
    multitaskStrategy: "reject",
    ...(config.command != null && { command: config.command }),
    ...(config.checkpointId != null && {
        checkpoint: { checkpoint_id: config.checkpointId },
    }),
    context: {
        ollama_host: configurable.ollamaHost || undefined,
        openai_api_url: configurable.openaiApiUrl || undefined,
        openai_api_key: configurable.openaiApiKey || undefined,
        model: configurable.model || undefined,
        db_toolbox_uri: configurable.dbToolboxUri || undefined,
        mongodb_mcp_uri: configurable.mongodbMcpUri || undefined,
        ms_sql_connection_string: configurable.mssqlConnectionString || undefined,
        mongodb_uri: configurable.mongodbUri || undefined,
        neo4j_uri: configurable.neo4jUri || undefined,
        neo4j_password: configurable.neo4jPassword || undefined,
        daytona_api_url: configurable.daytonaApiUrl || undefined,
        daytona_api_key: configurable.daytonaApiKey || undefined,
        daytona_target: configurable.daytonaTarget || undefined,
        sandbox_execution_timeout: configurable.daytonaTimeout || undefined,
    },
};

const eventStream = await client.runs.stream(externalId, ASSISTANT_ID, payload);

• abortSignal: An AbortController signal that can be triggered to cancel the stream.
• command: An optional command object (e.g. { resume: ... }), used by the InterruptHandler component to resume a suspended graph. Its resume value is forwarded verbatim to the backend interrupt() call (see §6).
• checkpointId: An optional string identifier for resuming from a specific checkpoint in the thread history.

​

2.1 LLM Backend Switcher

• Local Ollama Deployment: Directs requests to a local daemon (e.g., http://localhost:11434) running open-weights models like qwen2.5-coder.
• Remote Metacentrum e-INFRA CZ: Routes calls through Metacentrum’s OpenAI-compatible APIs, providing access to larger models like einfra/kimi-k2.6 or einfra/deepseek-v4-pro-thinking.

​

3. Sub-graphs, Event Handlers, & Custom Telemetry

​

3.1 Sub-graph State Merging

onSubgraphValues: (namespace: string, values: any) => {
    if (values) {
        setGraphState((prev) => ({ ...prev, ...values }));
    }
}

​

3.2 Custom Event Logs (onCustomEvent)

onCustomEvent: (type: string, data: any) => {
    console.log(`[UOM] Custom event [${type}]:`, data);
}

​

3.3 Noise Reduction Error Filtering

const EXCLUDED_ERRORS = ["signal is aborted without reason"];

const handleError = (msg: string, error?: any) => {
    if (EXCLUDED_ERRORS.includes(error?.message)) {
        console.warn("Excluded error occurred:", error);
        return;
    }
    console.error(`[UOM Error] ${msg}:`, error);
};

​

5. Thread List Synchronization (RemoteThreadListAdapter)

​

5.1 Adapter Methods

• list(): Queries the thread catalog using client.threads.search (returning up to 50 threads sorted by creation date descending):
  list: async () => {
      return await client.threads.search({ limit: 50 });
  }
  
• rename(remoteId, newTitle): Updates metadata tags stored on the server:
  rename: async (remoteId, newTitle) => {
      await client.threads.update(remoteId, { metadata: { title: newTitle } });
  }
  
• delete(remoteId): Removes the thread from server persistence:
  delete: async (remoteId) => {
      await client.threads.delete(remoteId);
  }
  
• initialize(): Provisions a new thread identifier on the server, initialized with a timestamped title:
  initialize: async () => {
      const title = `Migration ${new Date().toISOString()}`;
      return await client.threads.create({ metadata: { title } });
  }
  
• fetch(threadId): Retrieves the current state and messages for the selected thread:
  fetch: async (threadId) => {
      return await client.threads.get(threadId);
  }
  

​

6. Interrupt & User Decision Flow (InterruptHandler)

• File Path: frontend/uom-translator-ui/components/assistant-ui/interrupt-handler.tsx
• Component: InterruptHandler

# services/orchestrator/src/react_agent/graph.py — human_intervention_node
response = interrupt({
    "instruction": "Review the current state, generated translation and validation results...",
    "state": {
        "translated_query_code": state.translated_query_code,
        "translated_schema_code": state.translated_schema_code,
        "explanation_message": state.explanation_message,
        "query_equivalence_deep_diffs": state.query_equivalence_deep_diffs,
    },
})
output = HumanInterventionResponse.model_validate(response)  # { decision, feedback }

​

6.1 State Transitions during Suspends

• useLangGraphInterruptState(): Accesses the active suspend payload via interrupt.value. The card renders whenever a payload is present.

  Do not gate on interrupt.resumable. That field is deprecated in @langchain/langgraph-sdk (≥ 1.x) and omitted by recent servers, so guarding on it hides the card entirely (both live and on reload).

• useLangGraphSendCommand(): Resumes execution by posting the decision object back to the suspended node. The value becomes the return value of the backend interrupt() call and is validated against the HumanInterventionResponse Pydantic model, so both fields are required and it must be an object — not a bare string or a JSON-encoded string:
  const resume =
      decision === "accept"
          ? { decision: "accept", feedback: "" }
          : { decision: "reject", feedback };
  // LangGraphCommand.resume is typed as `string` upstream, but the value is forwarded
  // verbatim to the server; cast past the narrow type.
  await sendCommand({ resume: resume as unknown as string });
  

​

6.2 Persistence across reloads

load: async (externalId) => {
    const state = await client.threads.getState(externalId, undefined, { subgraphs: true });
    return {
        messages: state.values?.messages || [],
        // Collect pending interrupts across all tasks; the runtime feeds interrupts[0]
        // into useLangGraphInterruptState().
        interrupts: (state.tasks ?? []).flatMap((task) => task.interrupts ?? []),
    };
}

Why native interrupt() rather than the tool-message approval pattern? The assistant-ui Approval UI tutorial resumes by appending a ToolMessage (via addResult) to a pending tool call. That mechanism is incompatible with interrupt() + Command(resume): addResult sends new input rather than a resume command, and it would require the backend graph to be rebuilt around a pending tool call. The native interrupt keeps the human-in-the-loop gate as a first-class checkpoint that persists and restores cleanly.