GitHub

API reference for Service.

A language model (made by make).

Attributes

AttributeTypeDescription
id_generatorIdService = id_generator

The ids of the model's requests (the IdGenerator in context at make, else the default one).

supports_system_messages_in_historyEffect[bool] | None

Whether the provider's effective configuration takes system messages after the first; run it in the request's context to respect scoped overrides. None when unknown.

span_transformerSpanTransformer | None

The CurrentSpanTransformer in context when the model was made (Effect's parentSpanTransformer); one in context at the call wins over it.

Functions

__init__

__init__(_generate, _stream, codec_transformer=default_codec_transformer, supports_system_messages_in_history=None, id_generator=default_id_generator, span_transformer=None, _decoders=None) -> None
ParameterTypeDescription
_generateGenerateFn
_streamStreamFn
codec_transformerCodecTransformer = default_codec_transformer
supports_system_messages_in_historyEffect[bool] | None = None
id_generatorIdService = default_id_generator
span_transformerSpanTransformer | None = None
_decodersdict[tuple[bool, bool, bool], tuple[tuple[AnyTool, ...], Any]] | None = None
def __init__(
    self,
    _generate: GenerateFn,
    _stream: StreamFn,
    codec_transformer: CodecTransformer = default_codec_transformer,
    supports_system_messages_in_history: Effect[bool] | None = None,
    id_generator: IdService = default_id_generator,
    span_transformer: SpanTransformer | None = None,
    _decoders: dict[tuple[bool, bool, bool], tuple[tuple[AnyTool, ...], Any]] | None = None,
) -> None:
    self._generate = _generate
    self._stream = _stream
    self._codec_transformer = codec_transformer
    self._supports_system_messages_in_history = supports_system_messages_in_history
    self.id_generator = id_generator
    self._made_span_transformer = span_transformer
    self._decoders = (
        dict[tuple[bool, bool, bool], tuple[tuple[AnyTool, ...], Any]]()
        if _decoders is None
        else _decoders
    )

codec_transformer

codec_transformer(schema) -> tuple[S.Top, JsonSchema]

The provider's form of schema for structured output: the codec that decodes the model's text and the JSON Schema sent with the request (default_codec_transformer unless the provider gave one). It may raise for a schema the provider cannot express; generate_object then fails with an UnsupportedSchemaError AiError.

ParameterTypeDescription
schemaS.Top

Returns tuple[S.Top, JsonSchema]

def codec_transformer(self, schema: S.Top) -> tuple[S.Top, JsonSchema]:
    """The provider's form of ``schema`` for structured output: the codec
    that decodes the model's text and the JSON Schema sent with the
    request (``default_codec_transformer`` unless the provider gave
    one). It may raise for a schema the provider cannot express;
    ``generate_object`` then fails with an ``UnsupportedSchemaError``
    ``AiError``."""
    return self._codec_transformer(schema)

generate_text

generate_text(prompt, *, toolkit=None, tool_choice='auto', concurrency='unbounded', disable_tool_call_resolution=False, tool_call_validation='strict') -> Effect[GenerateTextResponse[Any, Any], Any, Any]

See the module's generate_text.

ParameterTypeDescription
promptP.RawInput
toolkitAny = None
tool_choiceToolChoice = 'auto'
concurrencyConcurrency = 'unbounded'
disable_tool_call_resolutionbool = False
tool_call_validationToolCallValidation = 'strict'

Returns Effect[GenerateTextResponse[Any, Any], Any, Any]

def generate_text(
    self,
    prompt: P.RawInput,
    *,
    toolkit: Any = None,
    tool_choice: ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: ToolCallValidation = "strict",
) -> Effect[GenerateTextResponse[Any, Any], Any, Any]:
    """See the module's ``generate_text``."""

    def body(span: Span) -> Effect[GenerateTextResponse[Any, Any], Any, Any]:
        options = ProviderOptions(
            P.make(prompt),
            span=span,
            tool_call_validation=_validation(
                disable_tool_call_resolution, tool_call_validation
            ),
        )
        sent = [options]
        content = self._content(
            options, toolkit, tool_choice, concurrency, disable_tool_call_resolution, sent=sent
        )
        return self._transformed(content, sent).map(GenerateTextResponse[Any, Any])

    return self._spanned("LanguageModel.generateText", "generateText", body, {})

generate_object

generate_object(prompt, *, schema, object_name=None, toolkit=None, tool_choice='auto', concurrency='unbounded', disable_tool_call_resolution=False, tool_call_validation='strict', allow_empty=False) -> Effect[GenerateObjectResponse[Any, Any, Any], Any, Any]

See the module's generate_object.

ParameterTypeDescription
promptP.RawInput
schemaS.Top
object_namestr | None = None
toolkitAny = None
tool_choiceToolChoice = 'auto'
concurrencyConcurrency = 'unbounded'
disable_tool_call_resolutionbool = False
tool_call_validationToolCallValidation = 'strict'
allow_emptybool = False

Returns Effect[GenerateObjectResponse[Any, Any, Any], Any, Any]

def generate_object(
    self,
    prompt: P.RawInput,
    *,
    schema: S.Top,
    object_name: str | None = None,
    toolkit: Any = None,
    tool_choice: ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: ToolCallValidation = "strict",
    allow_empty: bool = False,
) -> Effect[GenerateObjectResponse[Any, Any, Any], Any, Any]:
    """See the module's ``generate_object``."""
    name = get_object_name(object_name, schema)

    def body(span: Span) -> Effect[GenerateObjectResponse[Any, Any, Any], Any, Any]:
        options = ProviderOptions(
            P.make(prompt),
            response_format=JsonFormat(name, schema),
            span=span,
            tool_call_validation=_validation(
                disable_tool_call_resolution, tool_call_validation
            ),
        )
        sent = [options]
        content = self._content(
            options, toolkit, tool_choice, concurrency, disable_tool_call_resolution, sent=sent
        )
        return self._transformed(content, sent).flat_map(
            lambda parts: self._structured(parts, schema, allow_empty=allow_empty).map(
                lambda value: GenerateObjectResponse[Any, Any, Any](parts, value)
            )
        )

    return self._spanned(
        "LanguageModel.generateObject",
        "generateObject",
        body,
        {"effect.ai.object_name": name},
    )

stream_text

stream_text(prompt, *, toolkit=None, tool_choice='auto', concurrency='unbounded', disable_tool_call_resolution=False, tool_call_validation='strict') -> Stream[Any, Any, Any]

See the module's stream_text.

ParameterTypeDescription
promptP.RawInput
toolkitAny = None
tool_choiceToolChoice = 'auto'
concurrencyConcurrency = 'unbounded'
disable_tool_call_resolutionbool = False
tool_call_validationToolCallValidation = 'strict'

Returns Stream[Any, Any, Any]

def stream_text(
    self,
    prompt: P.RawInput,
    *,
    toolkit: Any = None,
    tool_choice: ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: ToolCallValidation = "strict",
) -> Stream[Any, Any, Any]:
    """See the module's ``stream_text``."""
    from pyfect.stream import provide_service
    from pyfect.tracer._spans import make_span_scoped

    def with_span(span: Span) -> Effect[Stream[Any, Any, Any], Any, Any]:
        options = ProviderOptions(
            P.make(prompt),
            span=span,
            tool_call_validation=_validation(
                disable_tool_call_resolution, tool_call_validation
            ),
        )
        sent = [options]
        _annotate(span, "text", tool_choice, concurrency)
        stream = fx.service_option(ResponseIdTracker).flat_map(
            lambda found: with_tracker(
                options, found.value if found is not None else None, sent
            )
        )
        return self._span_transformer.flat_map(
            lambda transformer: stream.map(lambda s: transform(s, transformer, sent))
        )

    def transform(
        stream: Stream[Any, Any, Any],
        transformer: SpanTransformer | None,
        sent: list[ProviderOptions],
    ) -> Stream[Any, Any, Any]:
        # Effect: with no transformer the stream is returned as it is;
        # otherwise the parts are gathered and given to it at the end.
        if transformer is None:
            return stream
        parts: list[Any] = []

        def gather(chunk: tuple[Any, ...]) -> tuple[Any, ...]:
            parts.extend(chunk)
            return chunk

        return stream.map_array(gather).ensuring(fx.sync(lambda: transformer(sent[0], parts)))

    def with_tracker(
        options: ProviderOptions, tracker: Tracker | None, sent: list[ProviderOptions]
    ) -> Effect[Stream[Any, Any, Any], Any, Any]:
        if toolkit is None:
            error = A.pending_check(A.collect(options.prompt.content), None, "streamText")
            if error is not None:
                return fx.fail(error)
            request = _prepared(tracker, options, sent)
            deferred = options.tool_call_validation == "deferred"
            return fx.succeed(self._stream_parts(request, None, tracker, False, deferred))
        return _as_kit_effect(toolkit).flat_map(
            lambda kit: self._stream_with(
                kit,
                options,
                tracker,
                sent,
                tool_choice=tool_choice,
                concurrency=concurrency,
                disable_tool_call_resolution=disable_tool_call_resolution,
            )
        )

    span = make_span_scoped("LanguageModel.streamText", kind="client")
    stream = StreamC.unwrap(span.flat_map(with_span))
    return stream.catch_all(
        lambda error: StreamC.fail(
            _error("streamText", InvalidOutputError.from_schema_error(error))
            if isinstance(error, SchemaError)
            else error
        )
    ).pipe(provide_service(IdGenerator, self.id_generator))