AI.Endpoint behaviour (fnord v0.8.92)

API endpoint abstraction.

This behavior encapsulates the common mechanics for calling API endpoints via Http.post_json/3 and applying API-level retry semantics.

In particular, OpenAI rate limiting is surfaced as HTTP 429 with a JSON body containing an error code ("rate_limit_exceeded").

Callers implement endpoint_path/0 and then call AI.Endpoint.post_json/3.

Summary

endpoint()

headers()

http_error()

http_status()

payload()

response()

success()

endpoint_path()

Perform a JSON POST request against the endpoint module's endpoint_path/0. Retries up to 3 times when the server indicates throttling.

retry_limit()

The fixed retry limit for API calls.

@type endpoint() :: module()

@type headers() :: [{String.t(), String.t()}]

@type http_error() :: {:http_error, {http_status(), String.t()}}

@type http_status() :: integer()

@type payload() :: map()

@type response() :: success() | http_error() | transport_error()

@type success() :: {:ok, map()}

@type transport_error() :: {:transport_error, any()}

@callback endpoint_path() :: String.t()

@spec post_json(endpoint(), headers(), payload()) :: response()

Perform a JSON POST request against the endpoint module's endpoint_path/0. Retries up to 3 times when the server indicates throttling.

@spec retry_limit() :: pos_integer()

The fixed retry limit for API calls.