PtcLlmHttp (PtcLlmHttp v0.1.0)

Copy Markdown View Source

Bounded HTTP transport and wire codecs for LLM requests.

This package owns one narrow job: turn a validated request into at most one outbound HTTP/1.1 attempt, read a bounded response, and normalize it through an OpenAI-compatible codec. Everything about which model to call, whether to call it again, and what the answer means belongs to the consumer.

Scope

Owned here:

  • one-attempt bounded HTTP/1 transport (DNS, TCP, TLS, framing);
  • OpenAI-compatible chat-completion request and response codecs;
  • text, tool calls, declared structured output, streaming, reported usage;
  • physical outbound-connection admission; and
  • typed, bounded transport and wire errors.

Deliberately not owned here: model selection, provider failover, credential storage, application policy, call budgets, traces, pricing, model catalogs, and provider-native APIs.

Fixed transport behavior

  • HTTP/1.1 only, sending Connection: close;
  • no retries, no redirects, no decompression, no cookies;
  • no proxy, and no endpoint or credential lookup from the environment;
  • HTTPS whenever a credential is present, and plain HTTP only for a credential-free literal loopback target that the constructor allows; and
  • every external byte is bounded before it is accumulated.

Status

Pre-alpha. Bounded OpenAI-compatible text, tool, structured-output, and synchronous text-streaming calls are available.

Summary

Functions

call(runtime, target, request, options)

Performs one bounded non-streaming OpenAI-compatible attempt.

stream(runtime, target, request, on_chunk, options)

Performs one bounded OpenAI-compatible text-streaming attempt.

Functions

call(runtime, target, request, options)

@spec call(pid(), PtcLlmHttp.Target.t(), PtcLlmHttp.Request.t(), keyword()) ::
  {:ok, PtcLlmHttp.Response.t()} | {:error, PtcLlmHttp.Error.t()}

Performs one bounded non-streaming OpenAI-compatible attempt.

The options are exact and required: a call-local credential, one absolute deadline, and one aggregate attempt process budget. The function never retries or follows redirects.

stream(runtime, target, request, on_chunk, options)

@spec stream(
  pid(),
  PtcLlmHttp.Target.t(),
  PtcLlmHttp.Request.t(),
  (map() -> :cont | :halt),
  keyword()
) ::
  {:ok, PtcLlmHttp.StreamComplete.t()}
  | {:halted, PtcLlmHttp.StreamHalt.t()}
  | {:error, PtcLlmHttp.Error.t()}

Performs one bounded OpenAI-compatible text-streaming attempt.

The callback executes synchronously in the attempt's monitored callback process and must return :cont or :halt. No socket bytes are read while a callback invocation is outstanding.