GitHub

API reference for Service.

A chat. history is the conversation so far; set it to rewrite it.

Attributes

AttributeTypeDescription
history= history
exportEffect[object, AiError]

The history in its JSON wire form.

export_jsonEffect[str, AiError]

The history as JSON text.

Functions

__init__

__init__(history, after_call=None) -> None
ParameterTypeDescription
historyRef[P.Prompt]
after_callCallable[[P.Prompt], Effect[None]] | None = None
def __init__(
    self,
    history: Ref[P.Prompt],
    after_call: Callable[[P.Prompt], Effect[None]] | None = None,
) -> None:
    self.history = history
    self._lock = Semaphore(1)
    # Run after each call with the history from before it (Persisted's save).
    self._after_call = after_call

generate_text

generate_text(prompt: P.RawInput, *, toolkit: None = None, tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: Literal[True], tool_call_validation: Literal['deferred']) -> Effect[lm.GenerateTextResponse[str, Never], AiError, lm.LanguageModel]
generate_text(prompt: P.RawInput, *, toolkit: None = None, tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: bool = False, tool_call_validation: Literal['strict'] = 'strict') -> Effect[lm.GenerateTextResponse[Never, Never], AiError, lm.LanguageModel]
generate_text[NN: LiteralString, RP, EE, RR](prompt: P.RawInput, *, toolkit: _ToolkitInput[NN, RP, EE, RR], tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: Literal[True], tool_call_validation: Literal['deferred']) -> Effect[lm.GenerateTextResponse[str, RP], AiError | EE, lm.LanguageModel | RR]
generate_text[NN: LiteralString, RP, EE, RR](prompt: P.RawInput, *, toolkit: _ToolkitInput[NN, RP, EE, RR], tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: bool = False, tool_call_validation: Literal['strict'] = 'strict') -> Effect[lm.GenerateTextResponse[NN, RP], AiError | EE, lm.LanguageModel | RR]

language_model.generate_text on the history plus prompt.

ParameterTypeDescription
prompt
toolkit= None
tool_choice= 'auto'
concurrency= 'unbounded'
disable_tool_call_resolution= False
tool_call_validation= 'strict'
@overload
def generate_text(
    self,
    prompt: P.RawInput,
    *,
    toolkit: None = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: Literal[True],
    tool_call_validation: Literal["deferred"],
) -> Effect[lm.GenerateTextResponse[str, Never], AiError, lm.LanguageModel]: ...
@overload
def generate_text(
    self,
    prompt: P.RawInput,
    *,
    toolkit: None = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: Literal["strict"] = "strict",
) -> Effect[lm.GenerateTextResponse[Never, Never], AiError, lm.LanguageModel]: ...
@overload
def generate_text[NN: LiteralString, RP, EE, RR](
    self,
    prompt: P.RawInput,
    *,
    toolkit: _ToolkitInput[NN, RP, EE, RR],
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: Literal[True],
    tool_call_validation: Literal["deferred"],
) -> Effect[lm.GenerateTextResponse[str, RP], AiError | EE, lm.LanguageModel | RR]: ...
@overload
def generate_text[NN: LiteralString, RP, EE, RR](
    self,
    prompt: P.RawInput,
    *,
    toolkit: _ToolkitInput[NN, RP, EE, RR],
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: Literal["strict"] = "strict",
) -> Effect[lm.GenerateTextResponse[NN, RP], AiError | EE, lm.LanguageModel | RR]: ...
def generate_text(
    self,
    prompt: P.RawInput,
    *,
    toolkit: Any = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: lm.ToolCallValidation = "strict",
) -> Effect[Any, Any, Any]:
    """``language_model.generate_text`` on the history plus ``prompt``."""
    return self._call(
        prompt,
        lambda full: _model().flat_map(
            lambda model: model.generate_text(
                full,
                toolkit=toolkit,
                tool_choice=tool_choice,
                concurrency=concurrency,
                disable_tool_call_resolution=disable_tool_call_resolution,
                tool_call_validation=tool_call_validation,
            )
        ),
    ).with_span("Chat.generateText")

generate_object

generate_object[A](prompt: P.RawInput, *, schema: S.Codec[A, Any, Any, Any], object_name: str | None = None, toolkit: None = None, tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: Literal[True], tool_call_validation: Literal['deferred'], allow_empty: Literal[False] = False) -> Effect[lm.GenerateObjectResponse[str, Never, A], AiError, lm.LanguageModel]
generate_object[A](prompt: P.RawInput, *, schema: S.Codec[A, Any, Any, Any], object_name: str | None = None, toolkit: None = None, tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: bool = False, tool_call_validation: Literal['strict'] = 'strict', allow_empty: Literal[False] = False) -> Effect[lm.GenerateObjectResponse[Never, Never, A], AiError, lm.LanguageModel]
generate_object[A, NN: LiteralString, RP, EE, RR](prompt: P.RawInput, *, schema: S.Codec[A, Any, Any, Any], object_name: str | None = None, toolkit: _ToolkitInput[NN, RP, EE, RR], tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: Literal[True], tool_call_validation: Literal['deferred'], allow_empty: Literal[False] = False) -> Effect[lm.GenerateObjectResponse[str, RP, A], AiError | EE, lm.LanguageModel | RR]
generate_object[A, NN: LiteralString, RP, EE, RR](prompt: P.RawInput, *, schema: S.Codec[A, Any, Any, Any], object_name: str | None = None, toolkit: _ToolkitInput[NN, RP, EE, RR], tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: bool = False, tool_call_validation: Literal['strict'] = 'strict', allow_empty: Literal[False] = False) -> Effect[lm.GenerateObjectResponse[NN, RP, A], AiError | EE, lm.LanguageModel | RR]
generate_object[A](prompt: P.RawInput, *, schema: S.Codec[A, Any, Any, Any], object_name: str | None = None, toolkit: None = None, tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: Literal[True], tool_call_validation: Literal['deferred'], allow_empty: Literal[True]) -> Effect[lm.GenerateObjectResponse[str, Never, Option[A]], AiError, lm.LanguageModel]
generate_object[A](prompt: P.RawInput, *, schema: S.Codec[A, Any, Any, Any], object_name: str | None = None, toolkit: None = None, tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: bool = False, tool_call_validation: Literal['strict'] = 'strict', allow_empty: Literal[True]) -> Effect[lm.GenerateObjectResponse[Never, Never, Option[A]], AiError, lm.LanguageModel]
generate_object[A, NN: LiteralString, RP, EE, RR](prompt: P.RawInput, *, schema: S.Codec[A, Any, Any, Any], object_name: str | None = None, toolkit: _ToolkitInput[NN, RP, EE, RR], tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: Literal[True], tool_call_validation: Literal['deferred'], allow_empty: Literal[True]) -> Effect[lm.GenerateObjectResponse[str, RP, Option[A]], AiError | EE, lm.LanguageModel | RR]
generate_object[A, NN: LiteralString, RP, EE, RR](prompt: P.RawInput, *, schema: S.Codec[A, Any, Any, Any], object_name: str | None = None, toolkit: _ToolkitInput[NN, RP, EE, RR], tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: bool = False, tool_call_validation: Literal['strict'] = 'strict', allow_empty: Literal[True]) -> Effect[lm.GenerateObjectResponse[NN, RP, Option[A]], AiError | EE, lm.LanguageModel | RR]

language_model.generate_object on the history plus prompt.

ParameterTypeDescription
prompt
schema
object_name= None
toolkit= None
tool_choice= 'auto'
concurrency= 'unbounded'
disable_tool_call_resolution= False
tool_call_validation= 'strict'
allow_empty= False
@overload
def generate_object[A](
    self,
    prompt: P.RawInput,
    *,
    schema: S.Codec[A, Any, Any, Any],
    object_name: str | None = None,
    toolkit: None = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: Literal[True],
    tool_call_validation: Literal["deferred"],
    allow_empty: Literal[False] = False,
) -> Effect[lm.GenerateObjectResponse[str, Never, A], AiError, lm.LanguageModel]: ...
@overload
def generate_object[A](
    self,
    prompt: P.RawInput,
    *,
    schema: S.Codec[A, Any, Any, Any],
    object_name: str | None = None,
    toolkit: None = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: Literal["strict"] = "strict",
    allow_empty: Literal[False] = False,
) -> Effect[lm.GenerateObjectResponse[Never, Never, A], AiError, lm.LanguageModel]: ...
@overload
def generate_object[A, NN: LiteralString, RP, EE, RR](
    self,
    prompt: P.RawInput,
    *,
    schema: S.Codec[A, Any, Any, Any],
    object_name: str | None = None,
    toolkit: _ToolkitInput[NN, RP, EE, RR],
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: Literal[True],
    tool_call_validation: Literal["deferred"],
    allow_empty: Literal[False] = False,
) -> Effect[lm.GenerateObjectResponse[str, RP, A], AiError | EE, lm.LanguageModel | RR]: ...
@overload
def generate_object[A, NN: LiteralString, RP, EE, RR](
    self,
    prompt: P.RawInput,
    *,
    schema: S.Codec[A, Any, Any, Any],
    object_name: str | None = None,
    toolkit: _ToolkitInput[NN, RP, EE, RR],
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: Literal["strict"] = "strict",
    allow_empty: Literal[False] = False,
) -> Effect[lm.GenerateObjectResponse[NN, RP, A], AiError | EE, lm.LanguageModel | RR]: ...
@overload
def generate_object[A](
    self,
    prompt: P.RawInput,
    *,
    schema: S.Codec[A, Any, Any, Any],
    object_name: str | None = None,
    toolkit: None = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: Literal[True],
    tool_call_validation: Literal["deferred"],
    allow_empty: Literal[True],
) -> Effect[lm.GenerateObjectResponse[str, Never, Option[A]], AiError, lm.LanguageModel]: ...
@overload
def generate_object[A](
    self,
    prompt: P.RawInput,
    *,
    schema: S.Codec[A, Any, Any, Any],
    object_name: str | None = None,
    toolkit: None = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: Literal["strict"] = "strict",
    allow_empty: Literal[True],
) -> Effect[lm.GenerateObjectResponse[Never, Never, Option[A]], AiError, lm.LanguageModel]: ...
@overload
def generate_object[A, NN: LiteralString, RP, EE, RR](
    self,
    prompt: P.RawInput,
    *,
    schema: S.Codec[A, Any, Any, Any],
    object_name: str | None = None,
    toolkit: _ToolkitInput[NN, RP, EE, RR],
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: Literal[True],
    tool_call_validation: Literal["deferred"],
    allow_empty: Literal[True],
) -> Effect[
    lm.GenerateObjectResponse[str, RP, Option[A]], AiError | EE, lm.LanguageModel | RR
]: ...
@overload
def generate_object[A, NN: LiteralString, RP, EE, RR](
    self,
    prompt: P.RawInput,
    *,
    schema: S.Codec[A, Any, Any, Any],
    object_name: str | None = None,
    toolkit: _ToolkitInput[NN, RP, EE, RR],
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: Literal["strict"] = "strict",
    allow_empty: Literal[True],
) -> Effect[
    lm.GenerateObjectResponse[NN, RP, Option[A]], AiError | EE, lm.LanguageModel | RR
]: ...
def generate_object(
    self,
    prompt: P.RawInput,
    *,
    schema: S.Top,
    object_name: str | None = None,
    toolkit: Any = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: lm.ToolCallValidation = "strict",
    allow_empty: bool = False,
) -> Effect[Any, Any, Any]:
    """``language_model.generate_object`` on the history plus ``prompt``."""
    call = self._call(
        prompt,
        lambda full: _model().flat_map(
            lambda model: model.generate_object(
                full,
                schema=schema,
                object_name=object_name,
                toolkit=toolkit,
                tool_choice=tool_choice,
                concurrency=concurrency,
                disable_tool_call_resolution=disable_tool_call_resolution,
                tool_call_validation=tool_call_validation,
                allow_empty=allow_empty,
            )
        ),
    )
    name = lm.get_object_name(object_name, schema)
    return call.with_span("Chat.generateObject", attributes={"effect.ai.object_name": name})

stream_text

stream_text(prompt: P.RawInput, *, toolkit: None = None, tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: Literal[True], tool_call_validation: Literal['deferred']) -> Stream[R.StreamPart[str, Never], AiError, lm.LanguageModel]
stream_text(prompt: P.RawInput, *, toolkit: None = None, tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: bool = False, tool_call_validation: Literal['strict'] = 'strict') -> Stream[R.StreamPart[Never, Never], AiError, lm.LanguageModel]
stream_text[NN: LiteralString, RP, EE, RR](prompt: P.RawInput, *, toolkit: _ToolkitInput[NN, RP, EE, RR], tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: Literal[True], tool_call_validation: Literal['deferred']) -> Stream[R.StreamPart[str, RP], AiError | EE, lm.LanguageModel | RR]
stream_text[NN: LiteralString, RP, EE, RR](prompt: P.RawInput, *, toolkit: _ToolkitInput[NN, RP, EE, RR], tool_choice: lm.ToolChoice = 'auto', concurrency: Concurrency = 'unbounded', disable_tool_call_resolution: bool = False, tool_call_validation: Literal['strict'] = 'strict') -> Stream[R.StreamPart[NN, RP], AiError | EE, lm.LanguageModel | RR]

language_model.stream_text on the history plus prompt. The history gains the parts streamed, also when the stream is cut short.

ParameterTypeDescription
prompt
toolkit= None
tool_choice= 'auto'
concurrency= 'unbounded'
disable_tool_call_resolution= False
tool_call_validation= 'strict'
@overload
def stream_text(
    self,
    prompt: P.RawInput,
    *,
    toolkit: None = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: Literal[True],
    tool_call_validation: Literal["deferred"],
) -> Stream[R.StreamPart[str, Never], AiError, lm.LanguageModel]: ...
@overload
def stream_text(
    self,
    prompt: P.RawInput,
    *,
    toolkit: None = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: Literal["strict"] = "strict",
) -> Stream[R.StreamPart[Never, Never], AiError, lm.LanguageModel]: ...
@overload
def stream_text[NN: LiteralString, RP, EE, RR](
    self,
    prompt: P.RawInput,
    *,
    toolkit: _ToolkitInput[NN, RP, EE, RR],
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: Literal[True],
    tool_call_validation: Literal["deferred"],
) -> Stream[R.StreamPart[str, RP], AiError | EE, lm.LanguageModel | RR]: ...
@overload
def stream_text[NN: LiteralString, RP, EE, RR](
    self,
    prompt: P.RawInput,
    *,
    toolkit: _ToolkitInput[NN, RP, EE, RR],
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: Literal["strict"] = "strict",
) -> Stream[R.StreamPart[NN, RP], AiError | EE, lm.LanguageModel | RR]: ...
def stream_text(
    self,
    prompt: P.RawInput,
    *,
    toolkit: Any = None,
    tool_choice: lm.ToolChoice = "auto",
    concurrency: Concurrency = "unbounded",
    disable_tool_call_resolution: bool = False,
    tool_call_validation: lm.ToolCallValidation = "strict",
) -> Stream[Any, Any, Any]:
    """``language_model.stream_text`` on the history plus ``prompt``.
    The history gains the parts streamed, also when the stream is cut
    short."""

    def start() -> Stream[Any, Any, Any]:
        parts: list[Any] = []

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

        def use(full: P.Prompt) -> Any:
            streamed = StreamC.unwrap(
                _model().map(
                    lambda model: model.stream_text(
                        full,
                        toolkit=toolkit,
                        tool_choice=tool_choice,
                        concurrency=concurrency,
                        disable_tool_call_resolution=disable_tool_call_resolution,
                        tool_call_validation=tool_call_validation,
                    )
                )
            )
            return to_channel(streamed.map_array(collect))

        def release(full: P.Prompt, _: Exit[Any, Any]) -> Effect[object]:
            done = full.concat(P.from_response_parts(parts))
            return self.history.set(done).and_then(self._lock.release(1))

        acquire = (
            self._lock.take(1).and_then(self.history.get()).map(lambda h: h.concat(prompt))
        )
        # Effect's Channel.acquireUseRelease: the history is set when the
        # model's stream ends, before any finalizer added outside (the save).
        return from_channel(acquire_use_release(acquire, use, release))

    stream = StreamC.unwrap(fx.sync(start)).with_span("Chat.streamText")
    after = self._after_call
    if after is None:
        return stream
    return StreamC.unwrap(self.history.get().map(lambda before: stream.ensuring(after(before))))