Skip to content

openai_factory

Module for creating an OpenAI factory.

O1Factory

Bases: OpenAIFactory

An OpenAI o1 factory.

Used as the factory for o1 models which have unique functionality.

Source code in spark_instructor/factory/openai_factory.py 
 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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
class O1Factory(OpenAIFactory):
    """An OpenAI o1 factory.

    Used as the factory for o1 models which have unique functionality.
    """

    @classmethod
    def from_config(
        cls,
        mode: Optional[instructor.Mode] = None,
        base_url: Optional[str] = None,
        api_key: Optional[str] = None,
        **kwargs,
    ) -> "O1Factory":
        """Create an OpenAI factory from custom inputs."""
        return cls(get_openai_aclient(mode or instructor.Mode.JSON_O1, base_url, api_key))

    def format_messages(self, messages: SparkChatCompletionMessages) -> List[ChatCompletionMessageParam]:
        """Format messages by using default callable."""
        # Ignore system messages and images as they are not yet supported
        return [message(string_only=True) for message in messages.root if message.role != "system"]

    async def create(
        self,
        response_model: Type[T] | None,
        messages: SparkChatCompletionMessages,
        model: str,
        max_tokens: int,
        temperature: float,
        max_retries: int,
        **kwargs,
    ) -> ChatCompletion:
        """Create a completion response.

        This method sends a request to the API and returns the completion response.
        If a response_model is provided, it structures the response accordingly.
        We handle o1 ``max_completion_tokens`` independently.

        Args:
            response_model (Type[T] | None): Optional Pydantic model class for structuring the response.
            messages (SparkChatCompletionMessages): The input messages for the completion.
            model (str): The name or identifier of the AI model to use.
            max_tokens (int): The maximum number of tokens in the completion response.
            temperature (float): The sampling temperature for the model's output.
                Always set to 1 regardless of input (not supported for o1 yet).
            max_retries (int): The maximum number of retry attempts for failed requests.
            **kwargs: Additional keyword arguments for the API request.

        Returns:
            ChatCompletion: The completion response, formatted according to the OpenAI standard.
        """
        completion = await self.async_client.chat.completions.create(
            response_model=response_model,  # type: ignore
            messages=self.format_messages(messages),
            model=model,
            max_retries=max_retries,
            max_completion_tokens=max_tokens,
            temperature=1,
            **kwargs,
        )
        return self.format_completion(cast(ChatCompletion, completion))

    async def create_with_completion(
        self,
        response_model: Type[T],
        messages: SparkChatCompletionMessages,
        model: str,
        max_tokens: int,
        temperature: float,
        max_retries: int,
        **kwargs,
    ) -> Tuple[T, ChatCompletion]:
        """Create a Pydantic model instance along with the full completion response.

        This method sends a request to the API, formats the response into a Pydantic model,
        and returns both the model instance and the full completion details.
        We handle o1 ``max_completion_tokens`` independently.

        Args:
            response_model (Type[T]): The Pydantic model class for structuring the response.
            messages (SparkChatCompletionMessages): The input messages for the completion.
            model (str): The name or identifier of the AI model to use.
            max_tokens (int): The maximum number of tokens in the completion response.
            temperature (float): The sampling temperature for the model's output.
                Always set to 1 regardless of input (not supported by o1 yet).
            max_retries (int): The maximum number of retry attempts for failed requests.
            **kwargs: Additional keyword arguments for the API request.

        Returns:
            Tuple[T, ChatCompletion]: A tuple containing the Pydantic model instance and the full completion.
        """
        pydantic_object, completion = await self.async_client.chat.completions.create_with_completion(
            response_model=response_model,
            messages=self.format_messages(messages),
            model=model,
            max_retries=max_retries,
            max_completion_tokens=max_tokens,
            temperature=1,
            **kwargs,
        )
        return pydantic_object, self.format_completion(completion)

create(response_model, messages, model, max_tokens, temperature, max_retries, **kwargs) async

Create a completion response.

This method sends a request to the API and returns the completion response. If a response_model is provided, it structures the response accordingly. We handle o1 max_completion_tokens independently.

Parameters:

Name Type Description Default
response_model Type[T] | None

Optional Pydantic model class for structuring the response.

 required
messages SparkChatCompletionMessages

The input messages for the completion.

 required
model str

The name or identifier of the AI model to use.

 required
max_tokens int

The maximum number of tokens in the completion response.

 required
temperature float

The sampling temperature for the model's output. Always set to 1 regardless of input (not supported for o1 yet).

 required
max_retries int

The maximum number of retry attempts for failed requests.

 required
**kwargs

Additional keyword arguments for the API request.

 {}

Returns:

Name Type Description
ChatCompletion ChatCompletion

The completion response, formatted according to the OpenAI standard.
Source code in spark_instructor/factory/openai_factory.py 
 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
async def create(
    self,
    response_model: Type[T] | None,
    messages: SparkChatCompletionMessages,
    model: str,
    max_tokens: int,
    temperature: float,
    max_retries: int,
    **kwargs,
) -> ChatCompletion:
    """Create a completion response.

    This method sends a request to the API and returns the completion response.
    If a response_model is provided, it structures the response accordingly.
    We handle o1 ``max_completion_tokens`` independently.

    Args:
        response_model (Type[T] | None): Optional Pydantic model class for structuring the response.
        messages (SparkChatCompletionMessages): The input messages for the completion.
        model (str): The name or identifier of the AI model to use.
        max_tokens (int): The maximum number of tokens in the completion response.
        temperature (float): The sampling temperature for the model's output.
            Always set to 1 regardless of input (not supported for o1 yet).
        max_retries (int): The maximum number of retry attempts for failed requests.
        **kwargs: Additional keyword arguments for the API request.

    Returns:
        ChatCompletion: The completion response, formatted according to the OpenAI standard.
    """
    completion = await self.async_client.chat.completions.create(
        response_model=response_model,  # type: ignore
        messages=self.format_messages(messages),
        model=model,
        max_retries=max_retries,
        max_completion_tokens=max_tokens,
        temperature=1,
        **kwargs,
    )
    return self.format_completion(cast(ChatCompletion, completion))

create_with_completion(response_model, messages, model, max_tokens, temperature, max_retries, **kwargs) async

Create a Pydantic model instance along with the full completion response.

This method sends a request to the API, formats the response into a Pydantic model, and returns both the model instance and the full completion details. We handle o1 max_completion_tokens independently.

Parameters:

Name Type Description Default
response_model Type[T]

The Pydantic model class for structuring the response.

 required
messages SparkChatCompletionMessages

The input messages for the completion.

 required
model str

The name or identifier of the AI model to use.

 required
max_tokens int

The maximum number of tokens in the completion response.

 required
temperature float

The sampling temperature for the model's output. Always set to 1 regardless of input (not supported by o1 yet).

 required
max_retries int

The maximum number of retry attempts for failed requests.

 required
**kwargs

Additional keyword arguments for the API request.

 {}

Returns:

Type Description
Tuple[T, ChatCompletion]

Tuple[T, ChatCompletion]: A tuple containing the Pydantic model instance and the full completion.
Source code in spark_instructor/factory/openai_factory.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
async def create_with_completion(
    self,
    response_model: Type[T],
    messages: SparkChatCompletionMessages,
    model: str,
    max_tokens: int,
    temperature: float,
    max_retries: int,
    **kwargs,
) -> Tuple[T, ChatCompletion]:
    """Create a Pydantic model instance along with the full completion response.

    This method sends a request to the API, formats the response into a Pydantic model,
    and returns both the model instance and the full completion details.
    We handle o1 ``max_completion_tokens`` independently.

    Args:
        response_model (Type[T]): The Pydantic model class for structuring the response.
        messages (SparkChatCompletionMessages): The input messages for the completion.
        model (str): The name or identifier of the AI model to use.
        max_tokens (int): The maximum number of tokens in the completion response.
        temperature (float): The sampling temperature for the model's output.
            Always set to 1 regardless of input (not supported by o1 yet).
        max_retries (int): The maximum number of retry attempts for failed requests.
        **kwargs: Additional keyword arguments for the API request.

    Returns:
        Tuple[T, ChatCompletion]: A tuple containing the Pydantic model instance and the full completion.
    """
    pydantic_object, completion = await self.async_client.chat.completions.create_with_completion(
        response_model=response_model,
        messages=self.format_messages(messages),
        model=model,
        max_retries=max_retries,
        max_completion_tokens=max_tokens,
        temperature=1,
        **kwargs,
    )
    return pydantic_object, self.format_completion(completion)

format_messages(messages)

Format messages by using default callable.

Source code in spark_instructor/factory/openai_factory.py 
59
60
61
62
def format_messages(self, messages: SparkChatCompletionMessages) -> List[ChatCompletionMessageParam]:
    """Format messages by using default callable."""
    # Ignore system messages and images as they are not yet supported
    return [message(string_only=True) for message in messages.root if message.role != "system"]

from_config(mode=None, base_url=None, api_key=None, **kwargs) classmethod

Create an OpenAI factory from custom inputs.

Source code in spark_instructor/factory/openai_factory.py 
48
49
50
51
52
53
54
55
56
57
@classmethod
def from_config(
    cls,
    mode: Optional[instructor.Mode] = None,
    base_url: Optional[str] = None,
    api_key: Optional[str] = None,
    **kwargs,
) -> "O1Factory":
    """Create an OpenAI factory from custom inputs."""
    return cls(get_openai_aclient(mode or instructor.Mode.JSON_O1, base_url, api_key))

OpenAIFactory

Bases: ClientFactory

An OpenAI factory.

Used as default factory for most providers.

Source code in spark_instructor/factory/openai_factory.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
class OpenAIFactory(ClientFactory):
    """An OpenAI factory.

    Used as default factory for most providers.
    """

    @classmethod
    def from_config(
        cls,
        mode: Optional[instructor.Mode] = None,
        base_url: Optional[str] = None,
        api_key: Optional[str] = None,
        **kwargs,
    ) -> "OpenAIFactory":
        """Create an OpenAI factory from custom inputs."""
        return cls(get_openai_aclient(mode or instructor.Mode.TOOLS, base_url, api_key))

    def format_messages(self, messages: SparkChatCompletionMessages) -> List[ChatCompletionMessageParam]:
        """Format messages by using default callable."""
        return [message() for message in messages.root]

    def format_completion(self, completion: ChatCompletion) -> ChatCompletion:
        """Return standard OpenAI completion message."""
        return completion

format_completion(completion)

Return standard OpenAI completion message.

Source code in spark_instructor/factory/openai_factory.py 
37
38
39
def format_completion(self, completion: ChatCompletion) -> ChatCompletion:
    """Return standard OpenAI completion message."""
    return completion

format_messages(messages)

Format messages by using default callable.

Source code in spark_instructor/factory/openai_factory.py 
33
34
35
def format_messages(self, messages: SparkChatCompletionMessages) -> List[ChatCompletionMessageParam]:
    """Format messages by using default callable."""
    return [message() for message in messages.root]

from_config(mode=None, base_url=None, api_key=None, **kwargs) classmethod

Create an OpenAI factory from custom inputs.

Source code in spark_instructor/factory/openai_factory.py 
22
23
24
25
26
27
28
29
30
31
@classmethod
def from_config(
    cls,
    mode: Optional[instructor.Mode] = None,
    base_url: Optional[str] = None,
    api_key: Optional[str] = None,
    **kwargs,
) -> "OpenAIFactory":
    """Create an OpenAI factory from custom inputs."""
    return cls(get_openai_aclient(mode or instructor.Mode.TOOLS, base_url, api_key))