Skip to content

Internal ModelWrapper

ModelWrapper core interfaces and base classes used by backends.

Executable

Bases: Protocol[ModelWrapperResult]

Callable protocol representing a compiled prompt executable.

Source code in sieves/model_wrappers/core.py 
22
23
24
25
26
27
28
29
30
31
class Executable(Protocol[ModelWrapperResult]):
    """Callable protocol representing a compiled prompt executable."""

    def __call__(self, values: Sequence[dict[str, Any]]) -> Iterable[ModelWrapperResult | None]:
        """Execute prompt executable for given values.

        :param values: Values to inject into prompts.
        :return: Results for prompts.
        """
        ...

__call__(values)

Execute prompt executable for given values.

Parameters:

Name Type Description Default
values Sequence[dict[str, Any]]

Values to inject into prompts.

 required

Returns:

Type Description
Iterable[ModelWrapperResult | None]

Results for prompts.
Source code in sieves/model_wrappers/core.py 
25
26
27
28
29
30
31
def __call__(self, values: Sequence[dict[str, Any]]) -> Iterable[ModelWrapperResult | None]:
    """Execute prompt executable for given values.

    :param values: Values to inject into prompts.
    :return: Results for prompts.
    """
    ...

ModelWrapper

Base class for model wrappers handling model invocation and structured generation.

Source code in sieves/model_wrappers/core.py 
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
class ModelWrapper[ModelWrapperPromptSignature, ModelWrapperResult, ModelWrapperModel, ModelWrapperInferenceMode]:
    """Base class for model wrappers handling model invocation and structured generation."""

    def __init__(self, model: ModelWrapperModel, generation_settings: GenerationSettings):
        """Initialize model wrapper with model and generation settings.

        :param model: Instantiated model instance.
        :param generation_settings: Generation settings.
        """
        self._model = model
        self._generation_settings = generation_settings
        self._inference_kwargs = generation_settings.inference_kwargs or {}
        self._init_kwargs = generation_settings.init_kwargs or {}
        self._strict_mode = generation_settings.strict_mode

    @property
    def generation_settings(self) -> GenerationSettings:
        """Return generation settings.

        :return: Generation settings.
        """
        return self._generation_settings

    @property
    def model(self) -> ModelWrapperModel:
        """Return model instance.

        :return: Model instance.
        """
        return self._model

    @property
    @abc.abstractmethod
    def supports_few_shotting(self) -> bool:
        """Return whether model wrapper supports few-shotting.

        :return: Whether model wrapper supports few-shotting.
        """

    @property
    @abc.abstractmethod
    def inference_modes(self) -> type[ModelWrapperInferenceMode]:
        """Return supported inference modes.

        :return: Supported inference modes.
        """

    @abc.abstractmethod
    def build_executable(
        self,
        inference_mode: ModelWrapperInferenceMode,
        prompt_template: str | None,
        prompt_signature: type[ModelWrapperPromptSignature] | ModelWrapperPromptSignature,
        fewshot_examples: Sequence[pydantic.BaseModel] = (),
    ) -> Executable[ModelWrapperResult | None]:
        """Return a prompt executable for the given signature and mode.

        This wraps the model type‑native generation callable (e.g., DSPy Predict, Outlines Generator) with sieves’
        uniform interface.

        :param inference_mode: Inference mode to use (e.g. classification, JSON, ... - this is model type-specific).
        :param prompt_template: Prompt template.
        :param prompt_signature: Expected prompt signature type.
        :param fewshot_examples: Few-shot examples.
        :return: Prompt executable.
        """

    @staticmethod
    def convert_fewshot_examples(fewshot_examples: Sequence[pydantic.BaseModel]) -> list[dict[str, Any]]:
        """Convert few‑shot examples to dicts.

        :param fewshot_examples: Fewshot examples to convert.
        :return: Fewshot examples as dicts.
        """
        return [fs_example.model_dump(serialize_as_any=True) for fs_example in fewshot_examples]

    @staticmethod
    async def _execute_async_calls(calls: list[Coroutine[Any, Any, Any]] | list[Awaitable[Any]]) -> Any:
        """Execute a batch of async functions.

        :param calls: Async calls to execute.
        :return: Parsed response objects.
        """
        return await asyncio.gather(*calls)

generation_settings property

Return generation settings.

Returns:

Type Description
GenerationSettings

Generation settings.

inference_modes abstractmethod property

Return supported inference modes.

Returns:

Type Description
type[ModelWrapperInferenceMode]

Supported inference modes.

model property

Return model instance.

Returns:

Type Description
ModelWrapperModel

Model instance.

supports_few_shotting abstractmethod property

Return whether model wrapper supports few-shotting.

Returns:

Type Description
bool

Whether model wrapper supports few-shotting.

__init__(model, generation_settings)

Initialize model wrapper with model and generation settings.

Parameters:

Name Type Description Default
model ModelWrapperModel

Instantiated model instance.

 required
generation_settings GenerationSettings

Generation settings.

 required
Source code in sieves/model_wrappers/core.py 
37
38
39
40
41
42
43
44
45
46
47
def __init__(self, model: ModelWrapperModel, generation_settings: GenerationSettings):
    """Initialize model wrapper with model and generation settings.

    :param model: Instantiated model instance.
    :param generation_settings: Generation settings.
    """
    self._model = model
    self._generation_settings = generation_settings
    self._inference_kwargs = generation_settings.inference_kwargs or {}
    self._init_kwargs = generation_settings.init_kwargs or {}
    self._strict_mode = generation_settings.strict_mode

build_executable(inference_mode, prompt_template, prompt_signature, fewshot_examples=()) abstractmethod

Return a prompt executable for the given signature and mode.

This wraps the model type‑native generation callable (e.g., DSPy Predict, Outlines Generator) with sieves’ uniform interface.

Parameters:

Name Type Description Default
inference_mode ModelWrapperInferenceMode

Inference mode to use (e.g. classification, JSON, ... - this is model type-specific).

 required
prompt_template str | None

Prompt template.

 required
prompt_signature type[ModelWrapperPromptSignature] | ModelWrapperPromptSignature

Expected prompt signature type.

 required
fewshot_examples Sequence[BaseModel]

Few-shot examples.

 ()

Returns:

Type Description
Executable[ModelWrapperResult | None]

Prompt executable.
Source code in sieves/model_wrappers/core.py 
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
@abc.abstractmethod
def build_executable(
    self,
    inference_mode: ModelWrapperInferenceMode,
    prompt_template: str | None,
    prompt_signature: type[ModelWrapperPromptSignature] | ModelWrapperPromptSignature,
    fewshot_examples: Sequence[pydantic.BaseModel] = (),
) -> Executable[ModelWrapperResult | None]:
    """Return a prompt executable for the given signature and mode.

    This wraps the model type‑native generation callable (e.g., DSPy Predict, Outlines Generator) with sieves’
    uniform interface.

    :param inference_mode: Inference mode to use (e.g. classification, JSON, ... - this is model type-specific).
    :param prompt_template: Prompt template.
    :param prompt_signature: Expected prompt signature type.
    :param fewshot_examples: Few-shot examples.
    :return: Prompt executable.
    """

convert_fewshot_examples(fewshot_examples) staticmethod

Convert few‑shot examples to dicts.

Parameters:

Name Type Description Default
fewshot_examples Sequence[BaseModel]

Fewshot examples to convert.

 required

Returns:

Type Description
list[dict[str, Any]]

Fewshot examples as dicts.
Source code in sieves/model_wrappers/core.py 
101
102
103
104
105
106
107
108
@staticmethod
def convert_fewshot_examples(fewshot_examples: Sequence[pydantic.BaseModel]) -> list[dict[str, Any]]:
    """Convert few‑shot examples to dicts.

    :param fewshot_examples: Fewshot examples to convert.
    :return: Fewshot examples as dicts.
    """
    return [fs_example.model_dump(serialize_as_any=True) for fs_example in fewshot_examples]

PydanticModelWrapper

Bases: ABC, ModelWrapper[ModelWrapperPromptSignature, ModelWrapperResult, ModelWrapperModel, ModelWrapperInferenceMode]

Abstract super class for model wrappers using Pydantic signatures and results.

Note that this class also assumes the model wrapper accepts a prompt. This holds true for most model wrappers - it doesn't only for those with an idiosyncratic way to process prompts like DSPy, or decoder-only models which don't work with object-based signatures anyway.

If and once we add support for a Pydantic-based model wrapper that doesn't accept prompt templates, we'll adjust by modifying _infer() to accept an additional parameter specifying how to handle prompt/instruction injection (and we might have to make supports_few_shotting() model type-specific again).

Source code in sieves/model_wrappers/core.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
class PydanticModelWrapper(
    abc.ABC, ModelWrapper[ModelWrapperPromptSignature, ModelWrapperResult, ModelWrapperModel, ModelWrapperInferenceMode]
):
    """Abstract super class for model wrappers using Pydantic signatures and results.

    Note that this class also assumes the model wrapper accepts a prompt. This holds true for most model wrappers - it
    doesn't only for those with an idiosyncratic way to process prompts like DSPy, or decoder-only models which don't
    work with object-based signatures anyway.

    If and once we add support for a Pydantic-based model wrapper that doesn't accept prompt templates, we'll adjust by
    modifying `_infer()` to accept an additional parameter specifying how to handle prompt/instruction injection (and
    we might have to make `supports_few_shotting()` model type-specific again).
    """

    @classmethod
    def _create_template(cls, template: str | None) -> jinja2.Template:
        """Create Jinja2 template from template string.

        :param template: Template string.
        :return: Jinja2 template.
        """
        assert template, f"prompt_template has to be provided to {cls.__name__}."
        return jinja2.Template(template)

    @override
    @property
    def supports_few_shotting(self) -> bool:
        return True

    def _infer(
        self,
        generator: Callable[[list[str]], Iterable[ModelWrapperResult]],
        template: jinja2.Template,
        values: Sequence[dict[str, Any]],
        fewshot_examples: Sequence[pydantic.BaseModel],
    ) -> Iterable[ModelWrapperResult | None]:
        """Run inference in batches with exception handling.

        :param generator: Callable generating responses.
        :param template: Prompt template.
        :param values: Doc values to inject.
        :param fewshot_examples: Fewshot examples.
        :return: Results parsed from responses.
        """
        fewshot_examples_dict = ModelWrapper.convert_fewshot_examples(fewshot_examples)
        examples = {"examples": fewshot_examples_dict} if len(fewshot_examples_dict) else {}

        try:
            yield from generator([template.render(**doc_values, **examples) for doc_values in values])

        except Exception as err:
            if self._strict_mode:
                raise RuntimeError(
                    "Encountered problem when executing prompt. Ensure your few-shot examples and document "
                    "chunks contain sensible information."
                ) from err
            else:
                yield from (None for _ in range(len(values)))

generation_settings property

Return generation settings.

Returns:

Type Description
GenerationSettings

Generation settings.

inference_modes abstractmethod property

Return supported inference modes.

Returns:

Type Description
type[ModelWrapperInferenceMode]

Supported inference modes.

model property

Return model instance.

Returns:

Type Description
ModelWrapperModel

Model instance.

__init__(model, generation_settings)

Initialize model wrapper with model and generation settings.

Parameters:

Name Type Description Default
model ModelWrapperModel

Instantiated model instance.

 required
generation_settings GenerationSettings

Generation settings.

 required
Source code in sieves/model_wrappers/core.py 
37
38
39
40
41
42
43
44
45
46
47
def __init__(self, model: ModelWrapperModel, generation_settings: GenerationSettings):
    """Initialize model wrapper with model and generation settings.

    :param model: Instantiated model instance.
    :param generation_settings: Generation settings.
    """
    self._model = model
    self._generation_settings = generation_settings
    self._inference_kwargs = generation_settings.inference_kwargs or {}
    self._init_kwargs = generation_settings.init_kwargs or {}
    self._strict_mode = generation_settings.strict_mode

build_executable(inference_mode, prompt_template, prompt_signature, fewshot_examples=()) abstractmethod

Return a prompt executable for the given signature and mode.

This wraps the model type‑native generation callable (e.g., DSPy Predict, Outlines Generator) with sieves’ uniform interface.

Parameters:

Name Type Description Default
inference_mode ModelWrapperInferenceMode

Inference mode to use (e.g. classification, JSON, ... - this is model type-specific).

 required
prompt_template str | None

Prompt template.

 required
prompt_signature type[ModelWrapperPromptSignature] | ModelWrapperPromptSignature

Expected prompt signature type.

 required
fewshot_examples Sequence[BaseModel]

Few-shot examples.

 ()

Returns:

Type Description
Executable[ModelWrapperResult | None]

Prompt executable.
Source code in sieves/model_wrappers/core.py 
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
@abc.abstractmethod
def build_executable(
    self,
    inference_mode: ModelWrapperInferenceMode,
    prompt_template: str | None,
    prompt_signature: type[ModelWrapperPromptSignature] | ModelWrapperPromptSignature,
    fewshot_examples: Sequence[pydantic.BaseModel] = (),
) -> Executable[ModelWrapperResult | None]:
    """Return a prompt executable for the given signature and mode.

    This wraps the model type‑native generation callable (e.g., DSPy Predict, Outlines Generator) with sieves’
    uniform interface.

    :param inference_mode: Inference mode to use (e.g. classification, JSON, ... - this is model type-specific).
    :param prompt_template: Prompt template.
    :param prompt_signature: Expected prompt signature type.
    :param fewshot_examples: Few-shot examples.
    :return: Prompt executable.
    """

convert_fewshot_examples(fewshot_examples) staticmethod

Convert few‑shot examples to dicts.

Parameters:

Name Type Description Default
fewshot_examples Sequence[BaseModel]

Fewshot examples to convert.

 required

Returns:

Type Description
list[dict[str, Any]]

Fewshot examples as dicts.
Source code in sieves/model_wrappers/core.py 
101
102
103
104
105
106
107
108
@staticmethod
def convert_fewshot_examples(fewshot_examples: Sequence[pydantic.BaseModel]) -> list[dict[str, Any]]:
    """Convert few‑shot examples to dicts.

    :param fewshot_examples: Fewshot examples to convert.
    :return: Fewshot examples as dicts.
    """
    return [fs_example.model_dump(serialize_as_any=True) for fs_example in fewshot_examples]