---

Class ::nsmcp::ChatCompletionsBackend

::nsmcp::ChatCompletionsBackend create ... \
           [ -apiKeyFile:required apiKeyFile:required ] \
           [ -apiOptions (default "{} object {}") ] \
           [ -apiUrl:required apiUrl:required ] \
           [ -authenticator (default "::nsmcp::auth") ] \
           [ -authorizer (default "::nsmcp::authorization") ] \
           [ -maxApiRequests (default "16") ] \
           [ -maxHistoryBytes (default "1048576") ] \
           [ -maxOutputTokens (default "4096") ] \
           [ -maxResponseBytes (default "8388608") ] \
           [ -maxResultBytes (default "131072") ] \
           [ -maxToolCalls (default "32") ] \
           [ -model:required model:required ] \
           [ -mutex mutex ] \
           [ -registry (default "::nsmcp::tools") ] \
           [ -streamStore (default "") ] \
           [ -timeout (default "180") ] \
           [ -tokenFile:required tokenFile:required ]

Defined in /usr/local/ns/tcl/nsmcp/question-chat-completions.tcl

Class Relations

• class: ::nx::Class
• superclass: ::nsmcp::QuestionBackend

::nx::Class create ::nsmcp::ChatCompletionsBackend \
     -superclass ::nsmcp::QuestionBackend

Methods (to be applied on instances)

• describe (scripted, public)

   <instance of nsmcp::ChatCompletionsBackend> describe

  Describe the configured streaming chat-completions backend. Report provider settings and request limits without sending an API request.

  Returns:

  The backend metadata dictionary.

  Testcases:

  No testcase defined.

  return [dict create backend chat-completions model ${:model} apiUrl ${:apiUrl}  streaming true timeout ${:timeout} maxOutputTokens ${:maxOutputTokens}  maxToolCalls ${:maxToolCalls} maxApiRequests ${:maxApiRequests}]

• run (scripted, public)

   <instance of nsmcp::ChatCompletionsBackend> run question state \
      emit

  Execute a question through a temporary chat-completions runner. Forward the question, retained state and event callback; destroy the runner on every exit.

  Parameters:

  question (required)

  Question text supplied to the selected provider.

  state (required)

  Opaque retained provider continuation or scan state.

  emit (required)

  Event callback prefix; returning false requests cancellation.

  Returns:

  The runner's completion or continuation result.

  Testcases:

  No testcase defined.

  set runner [::nsmcp::ChatCompletionsRun new -backend [self] -emit $emit]
  try {
      return [$runner run $question $state]
  } finally {
      $runner destroy
  }

• streamClose (scripted, public)

   <instance of nsmcp::ChatCompletionsBackend> streamClose key

  Release shared state for a completed or aborted stream. Remove the buffer entry under the mutex; tolerate a key already removed by cleanup.

  Parameters:

  key (required)

  Retained stream or configuration key.

  Returns:

  The stream cleanup result.

  Testcases:

  No testcase defined.

  ns_mutex lock ${:mutex}
  try {
      nsv_unset -nocomplain ${:streamStore} $key
  } finally {
      ns_mutex unlock ${:mutex}
  }

• streamData (scripted, public)

   <instance of nsmcp::ChatCompletionsBackend> streamData key \
      fields

  Append bounded bytes from a streamed HTTP response. Serialize buffer and byte-counter updates and retain explicit overflow/error state.

  Parameters:

  key (required)

  Retained stream or configuration key.

  fields (required)

  HTTP callback dictionary containing newly received data.

  Returns:

  The callback update result.

  Testcases:

  No testcase defined.

  ns_mutex lock ${:mutex}
  try {
      if {[nsv_get ${:streamStore} $key record]} {
          set data [dict get $fields data]
          dict incr record total [string bytelength $data]
          if {[dict get $record total] > ${:maxResponseBytes}
              || [string bytelength [dict get $record data]] + [string bytelength $data] > 1048576} {
              dict set record error "API response exceeded its buffer or response size limit"
          } elseif {[dict get $record error] eq ""} {
              dict append record data $data
          }
          nsv_set ${:streamStore} $key $record
      }
  } finally {
      ns_mutex unlock ${:mutex}
  }
  # The request discards its normal output. Returning TCL_OK also works
  # with cores whose queued callback evaluator does not propagate BREAK.
  return

• streamDrain (scripted, public)

   <instance of nsmcp::ChatCompletionsBackend> streamDrain key

  Drain currently buffered response bytes. Swap out buffered data under the shared mutex while retaining response metadata and total-byte counters.

  Parameters:

  key (required)

  Retained stream or configuration key.

  Returns:

  The stream-state dictionary containing the drained data.

  Testcases:

  No testcase defined.

  ns_mutex lock ${:mutex}
  try {
      set record [nsv_get ${:streamStore} $key]
      set next $record
      dict set next data {}
      nsv_set ${:streamStore} $key $next
      return $record
  } finally {
      ns_mutex unlock ${:mutex}
  }

• streamHeaders (scripted, public)

   <instance of nsmcp::ChatCompletionsBackend> streamHeaders key \
      fields

  Record streamed HTTP response headers. Update status and content type under the shared response-buffer mutex while the stream remains active.

  Parameters:

  key (required)

  Retained stream or configuration key.

  fields (required)

  HTTP callback dictionary containing response status and headers.

  Returns:

  The callback update result.

  Testcases:

  No testcase defined.

  ns_mutex lock ${:mutex}
  try {
      if {[nsv_get ${:streamStore} $key record]} {
          dict set record status [dict get $fields status]
          dict set record contentType [ns_set iget [dict get $fields headers] content-type]
          nsv_set ${:streamStore} $key $record
      }
  } finally {
      ns_mutex unlock ${:mutex}
  }

• streamOpen (scripted, public)

   <instance of nsmcp::ChatCompletionsBackend> streamOpen

  Allocate shared state for a streamed HTTP response. Create an independent response buffer and counters before registering response callbacks.

  Returns:

  The new stream-state key.

  Testcases:

  No testcase defined.

  set key [ns_crypto::randombytes -encoding hex 16]
  nsv_set ${:streamStore} $key {data {} total 0 status 0 contentType {} error {}}
  return $key

---