Skip to content

Internal Engine

Engine core interfaces and base classes used by backends.

Engine

Bases: Generic[EnginePromptSignature, EngineResult, EngineModel, EngineInferenceMode]

Base class for engines wrapping model invocation and batching.

Source code in sieves/engines/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
class Engine(Generic[EnginePromptSignature, EngineResult, EngineModel, EngineInferenceMode]):
    """Base class for engines wrapping model invocation and batching."""

    def __init__(self, model: EngineModel, generation_settings: GenerationSettings):
        """Initialize engine 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) -> EngineModel:
        """Return model instance.

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

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

        :return: Whether engine supports few-shotting.
        """

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

        :return: Supported inference modes.
        """

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

        This wraps the engine‑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 engine-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[EngineInferenceMode]

Supported inference modes.

model property

Return model instance.

Returns:

Type Description
EngineModel

Model instance.

supports_few_shotting abstractmethod property

Return whether engine supports few-shotting.

Returns:

Type Description
bool

Whether engine supports few-shotting.

__init__(model, generation_settings)

Initialize engine with model and generation settings.

Parameters:

Name Type Description Default
model EngineModel

Instantiated model instance.

 required
generation_settings GenerationSettings

Generation settings.

 required
Source code in sieves/engines/core.py 
37
38
39
40
41
42
43
44
45
46
47
def __init__(self, model: EngineModel, generation_settings: GenerationSettings):
    """Initialize engine 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 engine‑native generation callable (e.g., DSPy Predict, Outlines Generator) with Sieves’ uniform interface.

Parameters:

Name Type Description Default
inference_mode EngineInferenceMode

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

 required
prompt_template str | None

Prompt template.

 required
prompt_signature type[EnginePromptSignature] | EnginePromptSignature

Expected prompt signature type.

 required
fewshot_examples Sequence[BaseModel]

Few-shot examples.

 ()

Returns:

Type Description
Executable[EngineResult | None]

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

    This wraps the engine‑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 engine-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/engines/core.py 
100
101
102
103
104
105
106
107
@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]

Executable

Bases: Protocol[EngineResult]

Callable protocol representing a compiled prompt executable.

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

    def __call__(self, values: Sequence[dict[str, Any]]) -> Iterable[EngineResult | 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[EngineResult | None]

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

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

PydanticEngine

Bases: ABC, Engine[EnginePromptSignature, EngineResult, EngineModel, EngineInferenceMode]

Abstract super class for engines using Pydantic signatures and results.

Note that this class also assumes the engine accepts a prompt. This holds true for most engines - it doesn't only for those with an idiocratic 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 engine 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() engine-specific again).

Source code in sieves/engines/core.py 
119
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
class PydanticEngine(abc.ABC, Engine[EnginePromptSignature, EngineResult, EngineModel, EngineInferenceMode]):
    """Abstract super class for engines using Pydantic signatures and results.

    Note that this class also assumes the engine accepts a prompt. This holds true for most engines - it doesn't only
    for those with an idiocratic 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 engine 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()` engine-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[EngineResult]],
        template: jinja2.Template,
        values: Sequence[dict[str, Any]],
        fewshot_examples: Sequence[pydantic.BaseModel],
    ) -> Iterable[EngineResult | 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 = Engine.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 type(err)(
                    "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[EngineInferenceMode]

Supported inference modes.

model property

Return model instance.

Returns:

Type Description
EngineModel

Model instance.

__init__(model, generation_settings)

Initialize engine with model and generation settings.

Parameters:

Name Type Description Default
model EngineModel

Instantiated model instance.

 required
generation_settings GenerationSettings

Generation settings.

 required
Source code in sieves/engines/core.py 
37
38
39
40
41
42
43
44
45
46
47
def __init__(self, model: EngineModel, generation_settings: GenerationSettings):
    """Initialize engine 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 engine‑native generation callable (e.g., DSPy Predict, Outlines Generator) with Sieves’ uniform interface.

Parameters:

Name Type Description Default
inference_mode EngineInferenceMode

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

 required
prompt_template str | None

Prompt template.

 required
prompt_signature type[EnginePromptSignature] | EnginePromptSignature

Expected prompt signature type.

 required
fewshot_examples Sequence[BaseModel]

Few-shot examples.

 ()

Returns:

Type Description
Executable[EngineResult | None]

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

    This wraps the engine‑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 engine-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/engines/core.py 
100
101
102
103
104
105
106
107
@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]