GitHub

language_model

API reference for language_model.

A LanguageModel over OpenRouter's Chat Completions API (Effect's OpenRouterLanguageModel)::

program.pipe(fx.provide(language_model.model("openai/gpt-4o-mini").layer)).pipe(
    fx.provide(client.layer_config(api_key=config.redacted("OPENROUTER_API_KEY")))
)

The configuration is OpenRouter's chat request (temperature, provider, reasoning, ...), sent as is, plus strict_json_schema: the strictness of a schema-backed response format, True by default for OpenAI models (openai/, gpt-, o1-, o3-, o4-), unsaid (None) for the others. Tool and response schemas are written for the model's family (Anthropic's, OpenAI's or the default; a strict tool on a default model gets OpenAI's strict subset), and a tool call's parameters are decoded with the codec its schema was sent with; provider-defined tools are not supported. Provider options under "openrouter" set cacheControl breakpoints, a file's fileName and the reasoningDetails replayed in later turns.

Types

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

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

Classes

Functions

codec_transformer

codec_transformer(model) -> T.CodecTransformer

The schema rewriting of the model's family.

ParameterTypeDescription
modelstr

Returns T.CodecTransformer

def codec_transformer(model: str) -> T.CodecTransformer:
    """The schema rewriting of the model's family."""
    if model.startswith(("anthropic/", "claude-")):
        return to_codec_anthropic
    if model.startswith(("openai/", "gpt-", "o1-", "o3-", "o4-")):
        return to_codec_openai
    return lm.default_codec_transformer

make

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

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

ParameterTypeDescription
modelstr
configModelConfig | None = None

Returns Effect[lm.Service, Never, OpenRouterClient]

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

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

    def request(options: lm.ProviderOptions) -> Effect[tuple[dict[str, Any], ToolCodecs], AiError]:
        built = current().flat_map(lambda cfg: _make_request(cfg, options, codecs))

        def annotate(
            prepared: tuple[dict[str, Any], ToolCodecs],
        ) -> tuple[dict[str, Any], ToolCodecs]:
            _annotate_request(options.span, prepared[0])
            return prepared

        return built.map(annotate)

    def build(client: ClientService) -> Effect[lm.Service]:
        def generate(options: lm.ProviderOptions) -> Effect[Sequence[lm.EncodedPart], AiError, Any]:
            def send(
                prepared: tuple[dict[str, Any], ToolCodecs],
            ) -> Effect[list[Part], AiError, Any]:
                body, tool_codecs = prepared

                def respond(sent: tuple[GT.ChatResult, Any]) -> Effect[list[Part], AiError, Any]:
                    raw, response = sent
                    _annotate_response(options.span, raw)
                    return make_response(raw, response, tool_codecs)

                return client.create_chat_completion(body).flat_map(respond)  # pyright: ignore[reportArgumentType]

            return request(options).flat_map(send)

        def stream(options: lm.ProviderOptions) -> Stream[lm.EncodedPart, AiError, Any]:
            def send(
                prepared: tuple[dict[str, Any], ToolCodecs],
            ) -> Effect[Stream[Part, AiError, Any], AiError]:
                body, tool_codecs = prepared
                return client.create_chat_completion_stream(body).map(  # pyright: ignore[reportArgumentType]
                    lambda sent: make_stream_response(
                        sent[1], sent[0], client.max_response_bytes, tool_codecs
                    )
                )

            built = request(options).flat_map(send)
            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 OpenRouterClient().flat_map(build)

layer

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

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

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

model

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

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

ParameterTypeDescription
modelstr
configModelConfig | None = None

Returns M.Model[lm.LanguageModel, OpenRouterClient]

def model(
    model: str, config: ModelConfig | None = None
) -> M.Model[lm.LanguageModel, OpenRouterClient]:
    """The model as a ``Model`` (provider ``"openrouter"``)."""
    return M.make("openrouter", 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)