GitHub

language_model

API reference for language_model.

OpenAI's Responses API as a LanguageModel (Effect's OpenAiLanguageModel)::

program.pipe(fx.provide(language_model.model("gpt-5").layer))
    .pipe(fx.provide(client.layer(api_key=key)))

Config holds CreateResponse fields (store, reasoning, max_output_tokens, conversation, ...) sent as they are, and the library's options: file_id_prefixes (file data starting with one is an uploaded file's id), text.verbosity, strict_json_schema (default True), use_item_references (with store, send earlier assistant items as references; default True) and reasoning_model (default: every model but the GPT-3/4 and chat families). with_config_override changes it for an effect.

Prompt parts read OpenAI options under options["openai"] and response parts carry OpenAI metadata under metadata["openai"], in Effect's spelling (itemId, encryptedContent, imageDetail, ...). In WebSocket mode (client.with_web_socket_mode) streams go over the socket and reasoning keeps its encrypted content.

Types

TypeDefinitionDescription
ModelConfigtype ModelConfig = ConfigService | Mapping[str, Any]

Options for a model; keys beyond ConfigService are sent as is.

Classes

Functions

make

make(*, model, config=None) -> Effect[lm.Service, Never, OpenAiClient]

A LanguageModel for model over the OpenAiClient; a provided Config overrides config per request.

ParameterTypeDescription
modelstr
configModelConfig | None = None

Returns Effect[lm.Service, Never, OpenAiClient]

def make(
    *, model: str, config: ModelConfig | None = None
) -> Effect[lm.Service, Never, OpenAiClient]:
    """A ``LanguageModel`` for ``model`` over the ``OpenAiClient``; a
    provided ``Config`` overrides ``config`` per request."""

    def current() -> Effect[ConfigService]:
        return P.current_config(Config, {"model": model}, config)

    def request(
        options: lm.ProviderOptions, names: NameMapper
    ) -> Effect[tuple[ConfigService, W.CreateResponse, bool, PT.StrictTools], AiError]:
        def build(cfg: ConfigService, socket: object) -> Effect[Any, AiError]:
            web_socket_mode = socket is not None
            strict = strict_tools(cfg)
            made = _make_request(cfg, options, names, strict, web_socket_mode)
            return made.map(lambda payload: (cfg, payload, web_socket_mode, strict))

        return current().flat_map(
            lambda cfg: fx.service_option(OpenAiSocket).flat_map(lambda s: build(cfg, s))
        )

    def build(client: ClientService) -> Effect[lm.Service]:
        def generate(options: lm.ProviderOptions) -> Effect[Sequence[lm.EncodedPart], AiError, Any]:
            names = NameMapper(options.tools)

            def send(
                made: tuple[ConfigService, W.CreateResponse, bool, PT.StrictTools],
            ) -> Effect[Any, AiError]:
                _, payload, _, strict = made
                _annotate_request(options.span, payload)

                def respond(sent: tuple[W.Response, Any]) -> Effect[list[Part], AiError, Any]:
                    raw, response = sent
                    _annotate_response(options.span, raw)
                    return make_response(options, raw, response, names, strict)

                return client.create_response(payload).flat_map(respond)

            return request(options, names).flat_map(send)

        def stream(options: lm.ProviderOptions) -> Stream[lm.EncodedPart, AiError, Any]:
            names = NameMapper(options.tools)

            def send(
                made: tuple[ConfigService, W.CreateResponse, bool, PT.StrictTools], ids: IdService
            ) -> Effect[Stream[Part, AiError, Any], AiError]:
                cfg, payload, web_socket_mode, strict = made
                _annotate_request(options.span, payload)
                concludes = (
                    not web_socket_mode
                    and cfg.get("store") is True
                    and cfg.get("use_item_references") is not False
                )
                return client.create_response_stream(payload).map(
                    lambda sent: make_stream_response(
                        options,
                        sent[1],
                        sent[0],
                        names,
                        ids,
                        strict=strict,
                        concludes_summaries=concludes,
                    )
                )

            built: Effect[Stream[Part, AiError, Any], AiError, Any] = request(
                options, names
            ).flat_map(lambda made: IdGenerator().flat_map(lambda ids: send(made, ids)))
            return St.unwrap(built).map(lambda part: _annotate_stream_part(options.span, part))

        return lm.make(
            generate_text=generate, stream_text=stream, codec_transformer=to_codec_openai
        )

    return OpenAiClient().flat_map(build)

layer

layer(*, model, config=None) -> L.Layer[lm.LanguageModel, Never, OpenAiClient]
ParameterTypeDescription
modelstr
configModelConfig | None = None

Returns L.Layer[lm.LanguageModel, Never, OpenAiClient]

def layer(
    *, model: str, config: ModelConfig | None = None
) -> L.Layer[lm.LanguageModel, Never, OpenAiClient]:
    return L.effect(lm.LanguageModel, make(model=model, config=config))

model

model(model, config=None) -> M.Model[lm.LanguageModel, OpenAiClient]

The model as a Model (provider "openai").

ParameterTypeDescription
modelstr
configModelConfig | None = None

Returns M.Model[lm.LanguageModel, OpenAiClient]

def model(model: str, config: ModelConfig | None = None) -> M.Model[lm.LanguageModel, OpenAiClient]:
    """The model as a ``Model`` (provider ``"openai"``)."""
    return M.make("openai", model, layer(model=model, config=config))

with_config_override

with_config_override(overrides) -> P.WithConfigOverride[ConfigService]

Run an effect with overrides merged over the current Config. Use with .pipe.

ParameterTypeDescription
overridesConfigService

Returns P.WithConfigOverride[ConfigService]

def with_config_override(overrides: ConfigService) -> P.WithConfigOverride[ConfigService]:
    """Run an effect with ``overrides`` merged over the current ``Config``.
    Use with ``.pipe``."""
    return P.WithConfigOverride(Config, overrides)