> built 2026-10-14 00:42 UTC from 617693d (main) · oa 0.1.60. Details: build_info.json

# index.html.md

<!-- generated by epythet -->

# oa

Python interface to OpenAi

To install:	`pip install oa`

- [oa]()
- [Usage]()
  - [A collection of prompt-enabled functions]()
    - [PromptFuncs]()
  - [Functionalizing prompts]()
  - [Enforcing json formatted outputs]()
  - [Just-do-it: A minimal-boilerplate facade to OpenAI stuff]()
  - [Raw form - When you need to be closer to the metal]()

# Usage

Sure, you can do many things in English now with our new AI superpowers, but still, to be able to really reuse and compose your best prompts, you had better parametrize them – that is, distill them down to the minimal necessary interface. The function.

What `oa` does for you is enable you to easily – really easily – harness the newly available super-powers of AI from python.

Below, you’ll see how

See notebooks:

* [oa - An OpenAI facade.ipynb](https://github.com/thorwhalen/oa/blob/main/misc/oa%20-%20An%20OpenAI%20facade.ipynb)
* [oa - Making an Aesop fables children’s book oa.ipynb](https://github.com/thorwhalen/oa/blob/main/misc/oa%20-%20Making%20an%20Aesop%20fables%20children's%20book%20oa.ipynb)

Below are a few snippets from there.

## A collection of prompt-enabled functions

One main functionality that `oa` offers is an easy way to define python functions based
on AI prompts.
In order to demo these, we’ve made a few ready-to-use ones, which you can access via
`oa.ask.ai`:

```python
from oa.ask import ai

list(ai)
```

```none
['define_jargon', 'suggest_names', ..., 'make_synopsis']
```

These are the names of functions automatically generated from a (for now small) folder of prompt templates.

These functions all have propert signatures:

```python
import inspect

print(inspect.signature(ai.suggest_names))
```

(\*, thing, n=’30’, min_length=’1’, max_length=’15’)

```python
answer = ai.suggest_names(
    thing="""
    A python package that provides python functions to do things,
    enabled by prompts sent to an OpenAI engine.
    """
)
print(answer)
```

```none
GyroPy
PromptCore
FlexiFunc
ProperPy
PyCogito
...
PyPrompter
FuncDomino
SmartPy
PyVirtuoso
```

### PromptFuncs

Above, all we did was scan some local text files that specify prompt templates and make an object that contained the functions they define. We used `oa.PromptFuncs` for that. You can do the same. What `PromptFuncs` uses itself, is a convenient `oa.prompt_function` function that transforms a template into a function. See more details in the next “Functionalizing prompts” section.

Let’s just scratch the surface of what `PromptFuncs` can do. For more, you can look at the documentation, including the docs for `ai.prompt_function`.

```python
from oa import PromptFuncs

funcs = PromptFuncs(
    template_store={
        "haiku": "Write haiku about {subject}. Only output the haiku.",
        "stylize": """
            Reword what I_SAY, using the style: {style:funny}.
            Only output the reworded text.
            I_SAY:
            {something}
        """,
    }
)

list(funcs)
```

```none
['haiku', 'stylize']
```

```python
import inspect

for name in funcs:
    print(f"{name}: {inspect.signature(funcs[name])}")
```

```none
haiku: (*, subject)
stylize: (*, something, style='funny')
```

```python
print(funcs.haiku(subject="The potential elegance of code"))
```

```none
Code speaks a language,
Elegant syntax dances,
Beauty in function.
```

```python
print(funcs.stylize(something="The mess that is spagetti code!"))
```

```none
Spaghetti code, the tangled web of chaos!
```

```python
print(funcs.stylize(something="The mess that is spagetti code!", style="poetic"))
```

```none
The tangled strands of code, a chaotic tapestry!
```

We used a `dict` to express our `func_name:template` specification, but note that it can be any `Mapping`. Therefore, you can source `PromptFuncs` with local files (example, using `dol.TextFiles`, like we did), a DB, or anything you can map to a key-value `Mapping` interface.

(We suggest you use the [dol](https://pypi.org/project/dol/) package, and ecosystem, to help out with that.)

## Functionalizing prompts

The `oa.prompt_function` is an easy to use, yet extremely configurable, tool to do that.

```python
from oa import prompt_function

template = """
I'd like you to give me help me understand domain-specific jargon. 
I will give you a CONTEXT and some WORDS. 
You will then provide me with a tab separated table (with columns name and definition)
that gives me a short definition of each word in the context of the context.
Only output the table, with no words before or after it, since I will be parsing the output
automatically.

CONTEXT:
{context}

WORDS:
{words}
"""

define_jargon = prompt_function(template, defaults=dict(context="machine learning"))
```

```python
# Let's look at the signature
import inspect

print(inspect.signature(define_jargon))
```

```none
(*, words, context='machine learning')
```

```python
response = define_jargon(
    words="supervised learning\tunsupervised learning\treinforcement learning"
)
print(response)
```

```none
name	definition
supervised learning	A type of machine learning where an algorithm learns from labeled training data to make predictions or take actions. The algorithm is provided with input-output pairs and uses them to learn patterns and make accurate predictions on new, unseen data.
unsupervised learning	A type of machine learning where an algorithm learns patterns and structures in input data without any labeled output. The algorithm identifies hidden patterns and relationships in the data to gain insights and make predictions or classifications based on the discovered patterns.
reinforcement learning	A type of machine learning where an algorithm learns to make a sequence of decisions in an environment to maximize a cumulative reward. The algorithm interacts with the environment, receives feedback in the form of rewards or punishments, and adjusts its actions to achieve the highest possible reward over time.
```

```python
def table_str_to_dict(table_str, *, newline="\n", sep="   "):
    return dict([x.split("   ") for x in table_str.split("\n")[1:]])


table_str_to_dict(
    define_jargon(
        words="\n".join(["allomorph", "phonology", "phonotactic constraints"]),
        context="linguistics",
    )
)
```

```none
{'allomorph': 'A variant form of a morpheme that is used in a specific linguistic context, often resulting in different phonetic realizations.',
 'phonology': 'The study of speech sounds and their patterns, including the way sounds are organized and used in a particular language or languages.',
 'phonotactic constraints': 'The rules or restrictions that govern the possible combinations of sounds within a language, specifying what sound sequences are allowed and which ones are not.'}
```

Check out the many ways you can configure your function with `prompt_function`:

```python
str(inspect.signature(prompt_function)).split(", ")
```

```none
['(template',
 '*',
 'defaults: Optional[dict] = None',
 'template_to_names=<function _extract_names_from_format_string at 0x106d20940>',
 'embodier=<function string_format_embodier at 0x106d204c0>',
 'name=None',
 'prompt_func=<function chat at 0x128420af0>',
 'prompt_func_kwargs=None',
 'egress=None)']
```

## Enforcing json formatted outputs

With some newer models (example, “gpt4o-mini”) you can request that only valid
json be given as a response, or even more: A json obeying a specific schema.
You control this via the `response_format` argument.

Let’s first use AI to get a json schema for characteristics of a programming language.
That’s a json, so why not use the `response_format` with `{"type": "json_object"}` to
get that schema!

```python
from oa import chat
from oa.util import data_files

# To make sure we get a json schema that is openAI compliant, we'll use an example of
# one in our prompt to AI to give us one...
example_of_a_openai_json_schema = example_of_a_openai_json_schema = data_files.joinpath(
    "json_schema_example.json"
).read_text()

json_schema_str = chat(
    "Give me the json of a json_schema I can use different characteristics of "
    "programming languages. This schema should be a valid schema to use as a "
    "response_format in the OpenAI API. "
    f"Here's an example:\n{example_of_a_openai_json_schema}",
    model="gpt-4o-mini",
    response_format={"type": "json_object"},
)
print(json_schema_str[:500] + "...")
```

```default
{
  "name": "programming_language_characteristics",
  "strict": false,
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "The name of the programming language."
      },
      "paradigm": {
        "type": "array",
        "items": {
          "type": "string",
          "description": "Programming paradigms the language follows, e.g., 'object-oriented', 'functional', etc."
        }
      },
      "designed_by": {
        "t...
```

Now we can use this schema to make an AI-enabled python function that will give
us characteristics of a language, but always using that fixed format.
This also means we’ll be able to stick an `egress` to our prompt function, so
that we always get our output in the form of an already decoded json (a `dict`).

```python
from oa import prompt_function
import json

properties_of_language = prompt_function(
    "Give me a json that describes characteristics of the programming language: {language}.",
    prompt_func=chat,
    prompt_func_kwargs=dict(
        model="gpt-4o-mini",
        response_format={
            "type": "json_schema",
            "json_schema": json.loads(json_schema_str),
        },
    ),
    egress=json.loads,
)

info = properties_of_language("Python")
print(f"{type(info)=}\n")

from pprint import pprint

pprint(info)
```

```default
type(info)=<class 'dict'>

{'designed_by': ['Guido van Rossum'],
 'first_appeared': 1991,
 'influenced_by': ['ABC', 'C', 'C++', 'Java', 'Modula-3', 'Lisp'],
 'influences': ['Ruby', 'Swift', 'Matlab', 'Go'],
 'latest_release': '3.11.5',
 'name': 'Python',
 'paradigm': ['object-oriented', 'imperative', 'functional', 'procedural'],
 'typing_discipline': 'dynamic',
 'website': 'https://www.python.org'}
```

## Just-do-it: A minimal-boilerplate facade to OpenAI stuff

For the typical tasks you might want to use OpenAI for.

Note there’s no “enter API KEY here” code. That’s because if you don’t have it in the place(s) it’ll look for it, it will simply ask you for it, and, with your permission, put it in a hidden file for you, so you don’t have to do this every time.

```python
import oa
```

```python
print(oa.complete("chatGPT is a"))
```

```none
 chatbot based on OpenAI's GPT-2, a natural language processing
```

```python
print(oa.chat("Act as a chatGPT expert. List 5 useful prompt templates"))
```

```none
Sure, here are 5 useful prompt templates that can be used in a chatGPT session:

1. Can you provide some more details about [topic]?
- Examples: Can you provide some more details about the symptoms you're experiencing? Or Can you provide some more details about the issue you're facing with the website?

2. How long have you been experiencing [issue]?
- Examples: How long have you been experiencing the trouble with your internet connection? Or How long have you been experiencing the pain in your back?

3. Have you tried any solutions to resolve [issue]?
- Examples: Have you tried any solutions to resolve the error message you're seeing? Or Have you tried any solutions to resolve the trouble you're having with the application?

4. What is the specific error message you are receiving?
- Examples: What is the specific error message you are receiving when you try to log in? Or What is the specific error message you are receiving when you try to submit the form?

5. Is there anything else you would like to add that might be helpful for me to know?
- Examples: Is there anything else you would like to add that might be helpful for me to know about your situation? Or Is there anything else you would like to add that might be helpful for me to know about the product you are using?
```

```python
url = oa.dalle("An image of Davinci, pop art style")
print(url)
```

```none
https://oaidalleapiprodscus.blob.core.windows.net/private/org-AY3lr3H3xB9yPQ0HGR498f9M/user-7ZNCDYLWzP0GT48V6DCiTFWt/img-pNE6fCWGN3eJGj7ycFwZREhi.png?st=2023-04-22T22%3A17%3A03Z&se=2023-04-23T00%3A17%3A03Z&sp=r&sv=2021-08-06&sr=b&rscd=inline&rsct=image/png&skoid=6aaadede-4fb3-4698-a8f6-684d7786b067&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skt=2023-04-22T21%3A08%3A14Z&ske=2023-04-23T21%3A08%3A14Z&sks=b&skv=2021-08-06&sig=5j6LPVO992R95dllAAjbmOXzS0MORD06Fo8unwtGNl0%3D
```

```python
from IPython.display import Image

Image(url=url)
```

![image](https://github.com/thorwhalen/oa/assets/1906276/6e7b2ac4-648c-4ec0-81bf-078208f4ac39)

## Raw form - When you need to be closer to the metal

The `raw` object is a thin layer on top of the `openai` package, which is itself a thin layer over the web requests.

What was unsatisfactory with the `openai` package is (1) finding the right function, (2) the signature of the function once you found it, and (3) the documentation of the function.
What raw contains is pointers to the main functionalities (not all available – yet), with nice signatures and documentation, extracted from the web service openAPI specs themselves.

For example, to ask chatGPT something, the openai function is `openai.ChatCompletion.create`, or to get simple completions, the function is `openai.Completion.create` whose help is:

```default
Help on method create in module openai.api_resources.completion:

create(*args, **kwargs) method of builtins.type instance
    Creates a new completion for the provided prompt and parameters.
    
    See https://platform.openai.com/docs/api-reference/completions/create for a list
    of valid parameters.
```

Not super helpful. It basically tells you to got read the docs elsewhere.

The corresponding `raw` function is `raw.completion`, and it’s help is a bit more like what you’d expect in a python function.

```python
help(oa.raw.chatcompletion)
```

```none
Help on Wrap in module openai.api_resources.chat_completion:

chatcompletion
    Creates a new chat completion for the provided messages and parameters.
    
            See https://platform.openai.com/docs/api-reference/chat-completions/create
            for a list of valid parameters.
    
    chatcompletion(
            model: str
            messages: List[oa.openai_specs.Message]
            *
            temperature: float = 1
            top_p: float = 1
            n: int = 1
            stream: bool = False
            stop=None
            max_tokens: int = None
            presence_penalty: float = 0
            frequency_penalty: float = 0
            logit_bias: dict = None
            user: str = None
    )
    
    :param model: ID of the model to use. Currently, only `gpt-3.5-turbo` and `gpt-3.5-turbo-0301` are supported.
    
    :param messages: The messages to generate chat completions for, in the [chat format](/docs/guides/chat/introduction).
    
    :param temperature: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both.
    
    :param top_p: An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both.
    
    :param n: How many chat completion choices to generate for each input message.
    
    :param stream: If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message.
    
    :param stop: Up to 4 sequences where the API will stop generating further tokens.
    
    :param max_tokens: The maximum number of tokens allowed for the generated answer. By default, the number of tokens the model can return will be (4096 - prompt tokens).
    
    :param presence_penalty: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. [See more information about frequency and presence penalties.](/docs/api-reference/parameter-details)
    
    :param frequency_penalty: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. [See more information about frequency and presence penalties.](/docs/api-reference/parameter-details)
    
    :param logit_bias: Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
    
    :param user: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices/end-user-ids).
```

```python
prompt = "List 5 top prompt engineering tricks to write good prompts for chatGPT"

resp = oa.raw.chatcompletion(
    messages=[
        {"role": "system", "content": "You are an expert at chatGPT"},
        {"role": "user", "content": prompt},
    ],
    model="gpt-3.5-turbo-0301",
    temperature=0.5,
    max_tokens=300,
)
resp
```

```none
<OpenAIObject chat.completion id=chatcmpl-78HMPgn3oy2fuvm6sLCgOsQvnTVYr at 0x11fd467a0> JSON: {
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Sure, here are 5 top prompt engineering tricks to write good prompts for chatGPT:\n\n1. Be Specific: Ensure that your prompts are specific and clear. The more specific your prompt, the better the response from chatGPT. Avoid using vague or ambiguous language.\n\n2. Use Open-Ended Questions: Open-ended questions encourage chatGPT to provide more detailed and personalized responses. Avoid using closed-ended questions that can be answered with a simple yes or no.\n\n3. Include Context: Providing context to your prompts helps chatGPT to better understand the topic and provide more relevant responses. Include any necessary background information or details to help guide chatGPT's response.\n\n4. Use Emotion: Including emotion in your prompts can help chatGPT generate more engaging and relatable responses. Consider using prompts that evoke emotions such as happiness, sadness, or excitement.\n\n5. Test and Refine: Experiment with different prompts and evaluate the responses from chatGPT. Refine your prompts based on the quality of the responses and continue to test and improve over time.",
        "role": "assistant"
      }
    }
  ],
  "created": 1682207713,
  "id": "chatcmpl-78HMPgn3oy2fuvm6sLCgOsQvnTVYr",
  "model": "gpt-3.5-turbo-0301",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 214,
    "prompt_tokens": 36,
    "total_tokens": 250
  }
}
```

```python
print(resp["choices"][0]["message"]["content"])
```

```none
Sure, here are 5 top prompt engineering tricks to write good prompts for chatGPT:

1. Be Specific: Ensure that your prompts are specific and clear. The more specific your prompt, the better the response from chatGPT. Avoid using vague or ambiguous language.

2. Use Open-Ended Questions: Open-ended questions encourage chatGPT to provide more detailed and personalized responses. Avoid using closed-ended questions that can be answered with a simple yes or no.

3. Include Context: Providing context to your prompts helps chatGPT to better understand the topic and provide more relevant responses. Include any necessary background information or details to help guide chatGPT's response.

4. Use Emotion: Including emotion in your prompts can help chatGPT generate more engaging and relatable responses. Consider using prompts that evoke emotions such as happiness, sadness, or excitement.

5. Test and Refine: Experiment with different prompts and evaluate the responses from chatGPT. Refine your prompts based on the quality of the responses and continue to test and improve over time.
```

# ChatDacc: Shared chats parser

The `ChatDacc` class gives you access of the main functionalities of the `chats.py` module.
It provides tools for analyzing and extracting data from shared ChatGPT conversations.
Here’s an overview of its main features, for more details, see
[this demo notebook](https://github.com/thorwhalen/oa/blob/main/misc/oa%20-%20chats%20acquisition%20and%20parsing.ipynb)

## Initialize with a URL

Begin by creating a ChatDacc object with a conversation’s shared URL:

```python
from oa.chats import ChatDacc

url = "https://chatgpt.com/share/6788d539-0f2c-8013-9535-889bf344d7d5"
dacc = ChatDacc(url)
```

## Access Basic Conversation Data

Retrieve minimal metadata (e.g., roles, timestamps, and content):

```python
dacc.basic_turns_data
```

Or directly get it as a Pandas DataFrame:

```python
dacc.basic_turns_df
```

## Explore Full Turn Data

Access all available fields for each message in the conversation:

```python
dacc.turns_data
```

Indexed access simplifies specific turn retrieval:

```python
dacc.turns_data_keys
turn_data = dacc.turns_data[dacc.turns_data_keys[3]]
```

## Extract Metadata

Metadata summarizing the conversation is available through:

```python
dacc.metadata
```

## Extract and Analyze URLs

Identify all URLs referenced within the conversation, including quoted and embedded sources:

```python
urls = dacc.url_data()
```

For richer context, you can include prior levels or retain tracking parameters:

urls_in_context = dacc.url_data(prior_levels_to_include=1, remove_chatgpt_utm=False)

## Get Full JSON

The raw JSON for the entire conversation can be accessed for in-depth analysis:

```python
dacc.full_json_dict
```

This tool simplifies data extraction and analysis from ChatGPT shared conversations, making it ideal for developers, researchers, and data analysts.

<p class="epythet-aggregates">This documentation as a single file: <a href="oa.md">oa.md</a> (Markdown, for agents).</p>


# _autosummary/oa.ask.html.md

# oa.ask

Access to already made prompt functions


# _autosummary/oa.audio.html.md

# oa.audio

OpenAI Audio tools

### Functions

| [`text_to_speech`](_autosummary/oa.audio.html.md#oa.audio.text_to_speech)(text, \*, input[, model, ...])   | Convert text to speech using OpenAI's TTS API.                |
|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| [`transcribe`](_autosummary/oa.audio.html.md#oa.audio.transcribe)(audio, \*, file[, model, ...])       | Transcribe an audio or video file using OpenAI's Whisper API. |
| [`transcription_to_srt`](_autosummary/oa.audio.html.md#oa.audio.transcription_to_srt)(transcription, \*[, ...])  | Convert a transcription dict to SRT format string.            |
| [`tts`](_autosummary/oa.audio.html.md#oa.audio.tts)(text, \*, input[, model, voice, ...])       | Convert text to speech using OpenAI's TTS API.                |

### oa.audio.text_to_speech(text, \*, input, model='tts-1', voice='alloy', response_format='mp3', client=None, instructions=<openai.Omit object>, speed=<openai.Omit object>, stream_format=<openai.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)

Convert text to speech using OpenAI’s TTS API.

* **Parameters:**
  * **text** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text to convert to speech
  * **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – TTS model to use
  * **voice** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Voice to use (alloy, echo, fable, onyx, nova, shimmer)
  * **response_format** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Audio format (‘mp3’, ‘opus’, ‘aac’, ‘flac’, ‘wav’, ‘pcm’)
  * **client** (`Union`[`OpenAI`, [`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict), [`None`](https://docs.python.org/3/builtins/constants.html#None)]) – OpenAI client instance, API key string, config dict, or None
  * **kwargs** – Additional parameters for the API
* **Returns:**
  Audio content as bytes

#### NOTE
Actual API calls require a valid API key

### oa.audio.transcribe(audio, \*, file, model='whisper-1', response_format='json', language=None, client=None, chunking_strategy=<openai.Omit object>, include=<openai.Omit object>, keywords=<openai.Omit object>, known_speaker_names=<openai.Omit object>, known_speaker_references=<openai.Omit object>, languages=<openai.Omit object>, prompt=<openai.Omit object>, stream=<openai.Omit object>, temperature=<openai.Omit object>, timestamp_granularities=<openai.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)

Transcribe an audio or video file using OpenAI’s Whisper API.

* **Parameters:**
  * **audio_file_path** – Path to the audio/video file to transcribe
  * **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Transcription model to use
  * **response_format** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Format for the response (‘json’, ‘text’, ‘srt’, ‘verbose_json’)
  * **language** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]) – Optional ISO-639-1 language code (e.g., ‘en’, ‘fr’)
  * **client** (`Union`[`OpenAI`, [`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict), [`None`](https://docs.python.org/3/builtins/constants.html#None)]) – OpenAI client instance, API key string, config dict, or None
  * **kwargs** – Additional parameters for the API
* **Returns:**
  Dict with ‘text’, ‘segments’, ‘language’, and ‘raw_response’

#### NOTE
Actual API calls require a valid audio file and API key

### oa.audio.transcription_to_srt(transcription, , segment_duration=None)

Convert a transcription dict to SRT format string.

* **Parameters:**
  * **transcription** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Dict with ‘text’ and optionally ‘segments’
  * **segment_duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – If segments missing, duration per generated segment
* **Return type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)
* **Returns:**
  SRT formatted string

```pycon
>>> result = transcription_to_srt({'text': 'Hello world'})
>>> 'Hello world' in result
True
```

### oa.audio.tts(text, \*, input, model='tts-1', voice='alloy', response_format='mp3', client=None, instructions=<openai.Omit object>, speed=<openai.Omit object>, stream_format=<openai.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)

Convert text to speech using OpenAI’s TTS API.

* **Parameters:**
  * **text** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text to convert to speech
  * **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – TTS model to use
  * **voice** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Voice to use (alloy, echo, fable, onyx, nova, shimmer)
  * **response_format** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Audio format (‘mp3’, ‘opus’, ‘aac’, ‘flac’, ‘wav’, ‘pcm’)
  * **client** (`Union`[`OpenAI`, [`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict), [`None`](https://docs.python.org/3/builtins/constants.html#None)]) – OpenAI client instance, API key string, config dict, or None
  * **kwargs** – Additional parameters for the API
* **Returns:**
  Audio content as bytes

#### NOTE
Actual API calls require a valid API key


# _autosummary/oa.base.html.md

# oa.base

Base oa functionality

### Functions

| `chat`([prompt, model, messages, audio, ...])                                                    |                                                                                 |
|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| `complete`(prompt[, model, best_of, echo, ...])                                                  |                                                                                 |
| [`compute_price`](_autosummary/oa.base.html.md#oa.base.compute_price)(model[, num_input_tokens, ...])   | Compute the price of a model given the number of input and output tokens        |
| `dalle`(prompt[, n, size, background, model, ...])                                               |                                                                                 |
| [`embeddings`](_autosummary/oa.base.html.md#oa.base.embeddings)([texts, batch_size, egress, ...])    | Get embeddings for a text or texts.                                             |
| [`list_engine_ids`](_autosummary/oa.base.html.md#oa.base.list_engine_ids)([pattern])                      | List the available engine IDs.                                                  |
| [`model_information`](_autosummary/oa.base.html.md#oa.base.model_information)(model, information)           | Get information about a model                                                   |
| [`normalize_text_input`](_autosummary/oa.base.html.md#oa.base.normalize_text_input)(texts)                     | Ensures the type of texts is an iterable of strings                             |
| [`text_is_valid`](_autosummary/oa.base.html.md#oa.base.text_is_valid)(texts[, token_count, model, ...]) | Check if text (a string or iterable of strings) is/are valid for a given model. |
| `validate_texts_for_embeddings`(texts, ...[, ...])                                               |                                                                                 |

### oa.base.compute_price(model, num_input_tokens=None, num_output_tokens=None)

Compute the price of a model given the number of input and output tokens

### oa.base.embeddings(texts=None, \*, batch_size=2048, egress=None, batch_callback=None, validate=True, valid_text_getter=<function \_raise_if_any_invalid>, model='text-embedding-3-small', client=None, dimensions=NOT_GIVEN, encoding_format=<openai.Omit object>, user=<openai.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)

Get embeddings for a text or texts.

* **Parameters:**
  * **texts** (`Union`[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Iterable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`KT`), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]]) – A string, an iterable of strings, or a dictionary of strings
  * **egress** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – A function that takes the embeddings and returns the desired output.
    If None, the output will be a list of embeddings. If False, no output will be
    returned, so the batch_callback had better be set to accumulate the results.
  * **batch_callback** ([`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`int`](https://docs.python.org/3/builtins/functions.html#int), [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)]], [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – A function that is called after each batch of embeddings is
    computed. This can be used for logging, saving, etc.
    One common use case is to save the intermediate results, in files, database,
    or in a list. This can be useful if you’re worried about the process failing
    and want to be able to resume from where you left off instead of having
    to start over (wasting time, and money).
    To accumulate the results in a list, you can set `results = []` and then
    use a lambda function like this:
    `batch_callback = lambda i, batch: results.extend(batch)`.
  * **validate** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool) | [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – If True, validate the text(s) before getting embeddings
  * **valid_text_getter** – A function that gets valid texts from the input texts
  * **model** – The model to use for embeddings
  * **client** – The OpenAI client to use
  * **dimensions** ([`int`](https://docs.python.org/3/builtins/functions.html#int) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – If given will reduce the dimensions of the full size embedding
    vectors to that size
  * **batch_size** ([`int`](https://docs.python.org/3/builtins/functions.html#int) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – The maximum number of texts to send in a single request
  * **extra_embeddings_params** – Extra parameters to pass to the embeddings API

```pycon
>>> from functools import partial
>>> dimensions = 3
>>> embeddings_ = partial(embeddings, dimensions=dimensions, validate=True)
```

Test with a single word:

```pycon
>>> text = "vector"
>>> result = embeddings_(text)
>>> result
[-0.4096039831638336, 0.3794299364089966, -0.8296127915382385]
>>> isinstance(result, list)
True
>>> len(result) == dimensions == 3
True
```

### Test with a list of words

```pycon
>>> texts = ["semantic", "vector"]
>>> result = embeddings_(texts)
>>> isinstance(result, list)
True
>>> len(result)
2
```

Two vectors; one for each word. Note that the second vector is the vector of
“vector”, which we’ve seen before.

```pycon
>>> result[1]
[-0.4096039831638336, 0.3794299364089966, -0.8296127915382385]
```

```pycon
>>> len(result[1]) == dimensions == 3
True
```

### Test with a dictionary of words

```pycon
>>> texts = {"adj": "semantic", "noun": "vector"}
>>> result = embeddings_(texts)
>>> isinstance(result, dict)
True
>>> len(result)
2
>>> result["noun"]
[-0.4096039831638336, 0.3794299364089966, -0.8296127915382385]
>>> len(result["adj"]) == len(result["noun"]) == dimensions == 3
True
```

If you don’t specify `texts`, you will get a “partial” function that you can
use later to compute embeddings for texts. This is useful if you want to
set some parameters (like `dimensions`, `validate`, etc.) and then use the
resulting function to compute embeddings for different texts later on.

```pycon
>>> embeddings_with_10_dimensions = embeddings_(texts=None, dimensions=10)
>>> isinstance(embeddings_with_10_dimensions, Callable)
True
```

### oa.base.list_engine_ids(pattern=None)

List the available engine IDs. Optionally filter by a regex pattern.

### oa.base.model_information(model, information)

Get information about a model

### oa.base.normalize_text_input(texts)

Ensures the type of texts is an iterable of strings

* **Return type:**
  [`Iterable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]

### oa.base.text_is_valid(texts, token_count=True, , model='text-embedding-3-small', max_tokens=None)

Check if text (a string or iterable of strings) is/are valid for a given model.

Text is valid if

- it is not empty
- the number of tokens in the text is less than or equal to the max_tokens

* **Parameters:**
  * **texts** (`Union`[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Iterable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`KT`), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]]) – a string or an iterable of strings
  * **token_count** – Specification of the token count of the text or texts
  * **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The model to use for token count
  * **max_tokens** – The maximum number of tokens allowed by the model

If token_count is an integer, it will check if it is less than or equal to the
`max_tokens`.

If token_count is True, it will compute the number of tokens in the text using the
model specified by `model` and check if it is less than or equal to `max_tokens`.

If token_count is False, it will not check the token count.

If token_count is an iterable, it will apply the same mechanism as above, to each
text in `texts` and the corresponding token count in `token_count`.
This means both texts and token_count(s) must be of the same length.

### Examples

```pycon
>>> text_is_valid('Hello, world!')
True
>>> text_is_valid('')
False
>>> text_is_valid('Alice ' * 9000)
False
>>> text_is_valid('Alice ' * 9000, token_count=False)
True
>>> list(text_is_valid(['Bob', '', 'Alice ' * 9000]))
[True, False, False]
>>> list(text_is_valid(['Bob', '', 'Alice ' * 9000], token_count=False))
[True, False, True]
```


# _autosummary/oa.batch_embeddings.html.md

# oa.batch_embeddings

Simplified interface for computing embeddings in bulk using OpenAI’s batch API.

This module provides a clean, reusable interface for generating embeddings from
text segments using OpenAI’s batch API, handling the async nature of the API
and providing status monitoring, error handling, and result aggregation.

### Functions

| [`compute_embeddings`](_autosummary/oa.batch_embeddings.html.md#oa.batch_embeddings.compute_embeddings)(segments[, model, ...])   | Compute embeddings for text segments using OpenAI's batch API.   |
|-----------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| [`compute_embeddings_df`](_autosummary/oa.batch_embeddings.html.md#oa.batch_embeddings.compute_embeddings_df)(segments[, model])     | Compute embeddings and return results as a pandas DataFrame.     |

### Classes

| [`BatchRequestCounts`](_autosummary/oa.batch_embeddings.html.md#oa.batch_embeddings.BatchRequestCounts)([completed, failed, total])   | Counts of batch requests by status                       |
|---------------------------------------------------------------------------------------------------|----------------------------------------------------------|
| [`BatchStatus`](_autosummary/oa.batch_embeddings.html.md#oa.batch_embeddings.BatchStatus)()                                    | Status constants for batch processing                    |
| [`EmbeddingsBatchProcess`](_autosummary/oa.batch_embeddings.html.md#oa.batch_embeddings.EmbeddingsBatchProcess)([segments, ...])          | Manages the lifecycle of batch embedding requests.       |
| [`ProcessingMall`](_autosummary/oa.batch_embeddings.html.md#oa.batch_embeddings.ProcessingMall)(\*[, current, segments, ...])     | Container for all stores needed during batch processing. |

### Exceptions

| [`BatchError`](_autosummary/oa.batch_embeddings.html.md#oa.batch_embeddings.BatchError)   | Base exception for batch processing errors   |
|---------------------------------------------------------------|----------------------------------------------|

### *exception* oa.batch_embeddings.BatchError

Bases: [`Exception`](https://docs.python.org/3/builtins/exceptions.html#Exception)

Base exception for batch processing errors

### *class* oa.batch_embeddings.BatchRequestCounts(completed=0, failed=0, total=0)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Counts of batch requests by status

### *class* oa.batch_embeddings.BatchStatus

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Status constants for batch processing

#### *classmethod* is_success(status)

Check if a status represents successful completion

* **Return type:**
  [`bool`](https://docs.python.org/3/builtins/functions.html#bool)

#### *classmethod* is_terminal(status)

Check if a status represents a terminal state

* **Return type:**
  [`bool`](https://docs.python.org/3/builtins/functions.html#bool)

### *class* oa.batch_embeddings.EmbeddingsBatchProcess(segments=None, processing_mall=None, , model='text-embedding-3-small', batch_size=1000, poll_interval=5.0, max_polls=None, verbosity=1, keep_processing_info=False, dacc=None, logger=None, \*\*embeddings_kwargs)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Manages the lifecycle of batch embedding requests.

This class handles submitting batch requests to the OpenAI API,
monitoring their status, retrieving results, and aggregating them.
It can be used as a context manager for automatic cleanup.

#### aggregate_results()

Aggregate all segments and embeddings from completed batches.

* **Return type:**
  [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`float`](https://docs.python.org/3/builtins/functions.html#float)]]]
* **Returns:**
  Tuple of (all_segments, all_embeddings)

#### get_status_summary()

Get a summary of batch statuses.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`int`](https://docs.python.org/3/builtins/functions.html#int)]
* **Returns:**
  Dictionary with counts of batches in each status

#### *property* is_complete *: [bool](https://docs.python.org/3/builtins/functions.html#bool)*

Check if batch processing is complete

#### *property* is_running *: [bool](https://docs.python.org/3/builtins/functions.html#bool)*

Check if batch processing is currently running

#### monitor_batches()

Monitor the status of all submitted batches until completion.

* **Return type:**
  [`None`](https://docs.python.org/3/builtins/constants.html#None)

#### *property* result *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[list](https://docs.python.org/3/builtins/stdtypes.html#list)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)], [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[list](https://docs.python.org/3/builtins/stdtypes.html#list)[[float](https://docs.python.org/3/builtins/functions.html#float)]]] | [None](https://docs.python.org/3/builtins/constants.html#None)*

Get the aggregated results if available

#### run()

Execute the complete batch embedding workflow and return results.

This method submits batches, monitors their status until completion,
and returns the aggregated results.

* **Return type:**
  [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`float`](https://docs.python.org/3/builtins/functions.html#float)]]]
* **Returns:**
  Tuple of (all_segments, all_embeddings)

#### submit_batches()

Submit all segment batches to the OpenAI API.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), `Batch`]
* **Returns:**
  Dictionary mapping batch IDs to batch objects

### *class* oa.batch_embeddings.ProcessingMall(, current=None, segments=None, finished=None, erred=None, embeddings=None)

Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)

Container for all stores needed during batch processing.

The ProcessingMall contains five stores, all keyed by batch_id:

- current: Batches that are currently being processed
- segments: The text segments corresponding to each batch
- finished: Completed batches
- erred: Batches that encountered errors
- embeddings: The computed embeddings for each batch

#### clear()

Clear all stores

* **Return type:**
  [`None`](https://docs.python.org/3/builtins/constants.html#None)

#### is_complete()

Check if processing is complete (no batches in current)

* **Return type:**
  [`bool`](https://docs.python.org/3/builtins/functions.html#bool)

#### *classmethod* with_folder(rootdir, store_cls=<class 'dol.filesys.JsonFiles'>)

Create a ProcessingMall with stores that persist to local files.

* **Parameters:**
  **rootdir** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Directory where the stores will be saved

### oa.batch_embeddings.compute_embeddings(segments, model='text-embedding-3-small', , batch_size=1000, poll_interval=5.0, max_polls=None, verbosity=1, processing_mall=None, keep_processing_info=False, dacc=None, return_process=False, logger=None, \*\*embeddings_kwargs)

Compute embeddings for text segments using OpenAI’s batch API.

This function manages the complete lifecycle of batch embedding requests,
from submitting batches to the API, monitoring their status, and
aggregating the results.

* **Parameters:**
  * **segments** (`Union`[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]]) – Text segments to embed, either as a list or a dictionary
  * **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – OpenAI embedding model to use
  * **batch_size** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum number of segments per batch
  * **poll_interval** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Seconds between status checks
  * **max_polls** ([`int`](https://docs.python.org/3/builtins/functions.html#int) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Maximum number of status checks before timing out
  * **verbosity** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Level of logging detail (0-2)
  * **processing_mall** ([`ProcessingMall`](_autosummary/oa.batch_embeddings.html.md#oa.batch_embeddings.ProcessingMall) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Optional custom ProcessingMall
  * **keep_processing_info** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to keep mall data after completion
  * **dacc** (`OaDacc` | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Optional custom OaDacc instance
  * **return_process** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, return the EmbeddingsBatchProcess object instead of results
  * **logger** ([`Logger`](https://docs.python.org/3/library/logging.html#logging.Logger) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Optional custom logger
  * **\*\*embeddings_kwargs** – Additional parameters for embedding generation
* **Returns:**
  Tuple of (segments, embeddings)
  If return_process is True:
  > EmbeddingsBatchProcess object for further interaction
* **Return type:**
  [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`float`](https://docs.python.org/3/builtins/functions.html#float)]]] | [`EmbeddingsBatchProcess`](_autosummary/oa.batch_embeddings.html.md#oa.batch_embeddings.EmbeddingsBatchProcess)

### oa.batch_embeddings.compute_embeddings_df(segments, model='text-embedding-3-small', \*\*kwargs)

Compute embeddings and return results as a pandas DataFrame.

* **Parameters:**
  * **segments** (`Union`[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]]) – Text segments to embed
  * **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – OpenAI embedding model to use
  * **\*\*kwargs** – Additional arguments passed to compute_embeddings
* **Return type:**
  pandas.DataFrame
* **Returns:**
  DataFrame with ‘segment’ and ‘embedding’ columns


# _autosummary/oa.batches.html.md

# oa.batches

Batch functionality

Useful links:

- Web tool: [https://platform.openai.com/batches/](https://platform.openai.com/batches/)
- API docs: [https://platform.openai.com/docs/api-reference/batch](https://platform.openai.com/docs/api-reference/batch)

### Functions

| `batch_info_to_segments_and_embeddings`(...)                                                       |                                                                         |
|----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| `batches_within_range`(batches_base, min_date)                                                     |                                                                         |
| `get_batch_id_and_obj`(oa_stores, batch)                                                           |                                                                         |
| `get_batch_obj`(oa_stores, batch)                                                                  |                                                                         |
| [`get_output_file_data`](_autosummary/oa.batches.html.md#oa.batches.get_output_file_data)(batch, \*, oa_stores[, ...]) | Get the output file data for a batch, if it has completed successfully. |
| `get_segments_and_embeddings`(batch_store, ...)                                                    |                                                                         |
| [`mk_batch_file_embeddings_task`](_autosummary/oa.batches.html.md#oa.batches.mk_batch_file_embeddings_task)(texts, \*[, ...])   | Create a batch task (json-)dicts for generating embeddings.             |
| [`on_complete`](_autosummary/oa.batches.html.md#oa.batches.on_complete)(oa_stores, batch_obj)                 | Return the output file if the batch completed successfully              |
| `raise_error`(error_obj)                                                                           |                                                                         |
| [`random_custom_id`](_autosummary/oa.batches.html.md#oa.batches.random_custom_id)([prefix, suffix])                | Make a random custom_id by using the current time in nanoseconds        |
| `request_counts`(batch_list)                                                                       |                                                                         |

### Exceptions

| [`BatchCancelledError`](_autosummary/oa.batches.html.md#oa.batches.BatchCancelledError)   |    |
|------------------------------------------------------------------------|----|
| [`BatchError`](_autosummary/oa.batches.html.md#oa.batches.BatchError)            |    |
| [`BatchExpiredError`](_autosummary/oa.batches.html.md#oa.batches.BatchExpiredError)     |    |
| [`BatchFailedError`](_autosummary/oa.batches.html.md#oa.batches.BatchFailedError)      |    |
| [`BatchFinalizingError`](_autosummary/oa.batches.html.md#oa.batches.BatchFinalizingError)  |    |
| [`BatchInProgressError`](_autosummary/oa.batches.html.md#oa.batches.BatchInProgressError)  |    |

### *exception* oa.batches.BatchCancelledError

Bases: [`BatchError`](_autosummary/oa.batches.html.md#oa.batches.BatchError)

### *exception* oa.batches.BatchError

Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError)

### *exception* oa.batches.BatchExpiredError

Bases: [`BatchError`](_autosummary/oa.batches.html.md#oa.batches.BatchError)

### *exception* oa.batches.BatchFailedError

Bases: [`BatchError`](_autosummary/oa.batches.html.md#oa.batches.BatchError)

### *exception* oa.batches.BatchFinalizingError

Bases: [`BatchError`](_autosummary/oa.batches.html.md#oa.batches.BatchError)

### *exception* oa.batches.BatchInProgressError

Bases: [`BatchError`](_autosummary/oa.batches.html.md#oa.batches.BatchError)

### oa.batches.get_output_file_data(batch, \*, oa_stores, get_batch_obj=<function get_batch_obj>, on_complete=<function on_complete>, on_error=<function raise_error>)

Get the output file data for a batch, if it has completed successfully.

### oa.batches.mk_batch_file_embeddings_task(texts, \*, custom_id=None, validate=True, valid_text_getter=<function \_raise_if_any_invalid>, model='text-embedding-3-small', dimensions=NOT_GIVEN, custom_id_per_text=None, \*\*extra_embeddings_params)

Create a batch task (json-)dicts for generating embeddings.

These dictionaries (or list thereof) are destined to be used as input for the
OpenAI API batch endpoint. The endpoint will then generate embeddings for the
provided texts.

* **Parameters:**
  * **texts** (`Union`[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Iterable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`KT`), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]]) – The text or list of texts to generate embeddings for.
  * **custom_id** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – A custom identifier for the batch task. Defaults to None.
  * **validate** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool) | [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Whether to validate the texts. Defaults to True.
  * **valid_text_getter** (*Optional* *[**Callable* *]* *,* *optional*) – Function to retrieve valid texts. Defaults to \_raise_if_any_invalid.
  * **model** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *optional*) – The embeddings model to use. Defaults to DFLT_EMBEDDINGS_MODEL.
  * **dimensions** ([`int`](https://docs.python.org/3/builtins/functions.html#int) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – The dimensions for the embeddings. Defaults to NOT_GIVEN.
  * **custom_id_per_text** (*Optional* *[*[*bool*](https://docs.python.org/3/builtins/functions.html#bool) *]* *,* *optional*) – Whether to include a custom ID per text item. Defaults to None.
  * **\*\*extra_embeddings_params** – Additional parameters for embeddings.
* **Returns:**
  A single task dictionary or a list of task dictionaries.
* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) | [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)]

### Examples

With a single text:

```pycon
>>> mk_batch_file_embeddings_task("Example text")
{'custom_id': '...',
 'method': 'POST',
 'url': '/v1/embeddings',
 'body': {'input': ['Example text'], 'model': 'text-embedding-3-small'}}
```

With a list of texts:

```pycon
>>> mk_batch_file_embeddings_task(["Text1", "Text2"])
{'custom_id': '...',
 'method': 'POST',
 'url': '/v1/embeddings',
 'body': {'input': ['Text1', 'Text2'], 'model': 'text-embedding-3-small'}}
```

With a dictionary of texts:

```pycon
>>> mk_batch_file_embeddings_task({"key1": "Text1", "key2": "Text2"})
[{'custom_id': 'key1',
  'method': 'POST',
  'url': '/v1/embeddings',
  'body': {'input': 'Text1', 'model': 'text-embedding-3-small'}},
 {'custom_id': 'key2',
  'method': 'POST',
  'url': '/v1/embeddings',
  'body': {'input': 'Text2', 'model': 'text-embedding-3-small'}}]
```

As you see, when a list is given, the batch task is created with a single custom_id,
with a list of texts as input.
When a dictionary is given, the batch task is created with
a custom_id per text item, and the input is a dictionary of key-value pairs.

The usefulness of giving a dictionary is that the tasks will contain the same keys
as your dictionary, which can be useful when having to link the results back to
the original data. But it comes with a disadvantage: it’s much faster to process
a list of texts than multiple tasks with a single text each.

When efficiency is a concern, you can keep a texts dictionary on the client side,
ask to embed list(texts.values()), and then use the keys to link the results back
to the original data.
You can force the function to ignore the type of the texts input and do it the way
you want it, by setting custom_id_per_text to True or False.

```pycon
>>> mk_batch_file_embeddings_task(
...     {"key1": "Text1", "key2": "Text2"}, custom_id_per_text=False
... )
{'custom_id': '...',
'method': 'POST',
'url': '/v1/embeddings',
'body': {'input': ['Text1', 'Text2'],
'model': 'text-embedding-3-small'}}
```

```pycon
>>> mk_batch_file_embeddings_task(
...     ["Text1", "Text2"], custom_id_per_text=True
... )
[{'custom_id': 0,
  'method': 'POST',
  'url': '/v1/embeddings',
  'body': {'input': 'Text1', 'model': 'text-embedding-3-small'}},
 {'custom_id': 1,
  'method': 'POST',
  'url': '/v1/embeddings',
  'body': {'input': 'Text2', 'model': 'text-embedding-3-small'}}]
```

### oa.batches.on_complete(oa_stores, batch_obj)

Return the output file if the batch completed successfully

### oa.batches.random_custom_id(prefix='custom_id-', suffix='')

Make a random custom_id by using the current time in nanoseconds


# _autosummary/oa.chats.html.md

# oa.chats

Tools to work with shared chats (conversations).

For instance: Extract information from them.

The main object here is `ChatDacc` (Chat Data Accessor), which is a class that allows
you to access the data in a shared chat in a structured way.

# >>> from oa.chats import ChatDacc
# >>>
# >>> url = ‘[https://chatgpt.com/share/6788d539-0f2c-8013-9535-889bf344d7d5](https://chatgpt.com/share/6788d539-0f2c-8013-9535-889bf344d7d5)’
# >>> dacc = ChatDacc(url)
# >>>
# >>> basic_turns_data = dacc.basic_turns_data
# >>> len(basic_turns_data)
# 4
# >>> first_turn = basic_turns_data[0]
# >>> isinstance(first_turn, dict)
# True
# >>> list(first_turn)
# [‘id’, ‘role’, ‘content’, ‘message_id’]
# >>> print(first_turn[‘content’])  # doctest: +NORMALIZE_WHITESPACE
# This conversation is meant to be used as an example, for testing, and/or for figuring out how to parse the html and json of a conversation.
# <BLANKLINE>
# As such, we’d like to keep it short.
# <BLANKLINE>
# Just say “Hello World!” back to me for now, and then in a second line write 10 random words.

### Functions

| [`find_all_matching_paths_in_list_values`](_autosummary/oa.chats.html.md#oa.chats.find_all_matching_paths_in_list_values)(...)       | Find all paths in a nested dictionary where target_value evaluates to True for elements in a list contained within the value.                                                |
|----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`find_url_keys`](_autosummary/oa.chats.html.md#oa.chats.find_url_keys)(data[, current_path])               | Recursively finds all paths in a JSON-like object (nested dicts/lists) where URL strings are present.                                                                        |
| [`get_rendered_html`](_autosummary/oa.chats.html.md#oa.chats.get_rendered_html)(url, \*[, headless, ...])       | Return the fully rendered HTML for `url` using Playwright (sync or async).                                                                                                   |
| [`get_rendered_html_async`](_autosummary/oa.chats.html.md#oa.chats.get_rendered_html_async)(url, \*[, headless, ...]) | Asynchronous version: return fully rendered HTML using Playwright async API.                                                                                                 |
| [`parse_chat_html`](_autosummary/oa.chats.html.md#oa.chats.parse_chat_html)(html)                             | Parses conversation data from a shared chat HTML file into a structured list of messages.                                                                                    |
| [`reduce_chat_html`](_autosummary/oa.chats.html.md#oa.chats.reduce_chat_html)(html)                            | Strips away all irrelevant metadata, headers, footers, and scripts from the raw HTML, keeping only the essential conversation content enclosed in the <div id="thread"> tag. |
| [`remove_utm_source`](_autosummary/oa.chats.html.md#oa.chats.remove_utm_source)(text)                           | Removes the "?utm_source=chatgpt.com" suffix from all URLs in the given text.                                                                                                |
| [`truncate_dict_values`](_autosummary/oa.chats.html.md#oa.chats.truncate_dict_values)(d[, max_length])             | Truncate string values in a dict to a maximum length for display purposes.                                                                                                   |

### Classes

| [`ChatDacc`](_autosummary/oa.chats.html.md#oa.chats.ChatDacc)(src)   | Chat Data Accessor - manages and extracts data from shared ChatGPT conversations.   |
|------------------------------------------------------------------|-------------------------------------------------------------------------------------|

### *class* oa.chats.ChatDacc(src)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Chat Data Accessor - manages and extracts data from shared ChatGPT conversations.

#### *property* basic_turns_data

Return the parsed conversation as-is (list of dicts with id, role, content, message_id).

#### *property* basic_turns_df

Convert the conversation to a pandas DataFrame.

#### copy_turns_json()

Copy the conversation data to clipboard as JSON.

#### *property* paths_containing_urls

Get unique paths containing URLs with array indices replaced by wildcards.

#### url_data(, remove_chatgpt_utm=True)

Extract all URLs from the conversation.

* **Parameters:**
  **remove_chatgpt_utm** – If True, remove utm_source=chatgpt.com from URLs
* **Returns:**
  List of URLs found in the conversation

#### *property* url_paths

Find all paths containing URLs in the conversation data.

### oa.chats.find_all_matching_paths_in_list_values(nested_dict, target_value)

Find all paths in a nested dictionary where target_value evaluates to True
for elements in a list contained within the value.

* **Parameters:**
  * **nested_dict** – The dictionary to search.
  * **target_value** ([`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable) | [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – A function that takes a value and returns a boolean.
    If a string, will be converted to a regex search.
* **Returns:**
  A generator yielding paths that match the condition.

```pycon
>>> nested_dict = {
...     "a": {"b": {"c": [1, 2, 3], "d": [4, 5]}},
...     "e": {"f": [6, 7], "g": {"h": [8, 9]}},
... }
>>> target_value_fn = lambda x: x % 2 == 0  # Find even numbers
>>> list(find_all_matching_paths_in_list_values(nested_dict, target_value_fn))
[('a', 'b', 'c'), ('a', 'b', 'd'), ('e', 'f'), ('e', 'g', 'h')]
```

### oa.chats.find_url_keys(data, current_path='')

Recursively finds all paths in a JSON-like object (nested dicts/lists) where URL strings are present.

This is a generator function that yields each path as a dot-separated string. Supports paths through
both dictionaries and lists.

* **Parameters:**
  * **data** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *or* [*list*](https://docs.python.org/3/builtins/stdtypes.html#list)) – The JSON-like object to search.
  * **current_path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The current path being traversed, used internally during recursion.
* **Yields:**
  *str* – Dot-separated path to a value containing a URL.

### Example

```pycon
>>> example_data = {
...     "key1": {
...         "nested": [
...             {"url": "http://example.com"},
...             {"url": "https://example.org"}
...         ]
...     },
...     "key2": "http://another-example.com"
... }
>>> list(find_url_keys(example_data))
['key1.nested[0].url', 'key1.nested[1].url', 'key2']
```

One thing you’ll probably want to do sometimes is transform, filter, and
aggregate these paths. Here’s an example of how you might get a list of
unique paths, with all array indices replaced with a wildcard, so thay
don’t appear as separate paths:

```pycon
>>> from functools import partial
>>> import re
>>> paths = find_url_keys(example_data)
>>> transform = partial(re.sub, '\[\d+\]', '[*]')
>>> unique_paths = set(map(transform, paths))
>>> sorted(unique_paths)
['key1.nested[*].url', 'key2']
```

### oa.chats.get_rendered_html(url, , headless=True, timeout=30000, use_async=False)

Return the fully rendered HTML for `url` using Playwright (sync or async).

By default this uses the synchronous Playwright API. If `use_async=True` the
async variant will be executed via asyncio.run.

#### NOTE
This function only imports Playwright when called. Install with:

pip install playwright
playwright install chromium

* **Return type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

### *async* oa.chats.get_rendered_html_async(url, , headless=True, timeout=30000)

Asynchronous version: return fully rendered HTML using Playwright async API.

* **Return type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

### oa.chats.parse_chat_html(html)

Parses conversation data from a shared chat HTML file into a structured list of messages.

It extracts the primary conversation data along with essential metadata:
‘id’ (from the turn ID), ‘role’, ‘content’, and ‘message_id’. The ‘time’
field is excluded as it cannot be reliably extracted from the visible HTML.

* **Parameters:**
  **html** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The full HTML content of the conversation file.
* **Return type:**
  [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]]
* **Returns:**
  A list of dictionaries, where each dictionary represents a message and
  contains ‘id’, ‘role’, ‘content’, and ‘message_id’ keys.

### oa.chats.reduce_chat_html(html)

Strips away all irrelevant metadata, headers, footers, and scripts from
the raw HTML, keeping only the essential conversation content enclosed in
the <div id=”thread”> tag.

This dramatically reduces the size of the HTML fed into the main parser
while preserving all necessary information for `parse_chat_html`.

* **Parameters:**
  **html** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The full HTML content of the conversation file.
* **Return type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)
* **Returns:**
  A stripped-down HTML string containing only the conversation thread.

### oa.chats.remove_utm_source(text)

Removes the “?utm_source=chatgpt.com” suffix from all URLs in the given text.

* **Parameters:**
  **text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The input text containing URLs.
* **Returns:**
  The text with the specified query parameter removed from all URLs.
* **Return type:**
  [*str*](https://docs.python.org/3/builtins/stdtypes.html#str)

### Example

```pycon
>>> input_text = (
...     "not_a_url "  # not even a url (won't be touched)
...     "http://abc?utm_source=chatgpt.com_not_at_the_end "  # target not at the end
...     "https://abc?utm_source=chatgpt.com "  # with ?
...     "https://abc&utm_source=chatgpt.com "  # with &
...     "http://abc?utm_source=chatgpt.com"  # with http instead of https
... )
>>> remove_utm_source(input_text)
'not_a_url http://abc_not_at_the_end https://abc https://abc http://abc'
```

### oa.chats.truncate_dict_values(d, max_length=100)

Truncate string values in a dict to a maximum length for display purposes.


# _autosummary/oa.html.md

# oa

Python facade to OpenAi functionality.

### Modules

| [`ask`](_autosummary/oa.ask.html.md#module-oa.ask)                           | Access to already made prompt functions                                         |
|----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [`audio`](_autosummary/oa.audio.html.md#module-oa.audio)                       | OpenAI Audio tools                                                              |
| [`base`](_autosummary/oa.base.html.md#module-oa.base)                         | Base oa functionality                                                           |
| [`batch_embeddings`](_autosummary/oa.batch_embeddings.html.md#module-oa.batch_embeddings) | Simplified interface for computing embeddings in bulk using OpenAI's batch API. |
| [`batches`](_autosummary/oa.batches.html.md#module-oa.batches)                   | Batch functionality                                                             |
| [`chats`](_autosummary/oa.chats.html.md#module-oa.chats)                       | Tools to work with shared chats (conversations).                                |
| [`oa_types`](_autosummary/oa.oa_types.html.md#module-oa.oa_types)                 | Types for oa                                                                    |
| [`openai_specs`](_autosummary/oa.openai_specs.html.md#module-oa.openai_specs)         | Tools to extract specs from the openai interface                                |
| [`stores`](_autosummary/oa.stores.html.md#module-oa.stores)                     | Data object layers for openai resources                                         |
| [`tools`](_autosummary/oa.tools.html.md#module-oa.tools)                       | Interface tools                                                                 |
| [`util`](_autosummary/oa.util.html.md#module-oa.util)                         | oa utils                                                                        |
| [`vector_stores`](_autosummary/oa.vector_stores.html.md#module-oa.vector_stores)       | Vector stores and search                                                        |


# _autosummary/oa.oa_types.html.md

# oa.oa_types

Types for oa

### Functions

| `heatmap_of_models_and_their_fields`()   |    |
|------------------------------------------|----|

### Classes

| [`BatchRequest`](_autosummary/oa.oa_types.html.md#oa.oa_types.BatchRequest)(\*\*data)        |                                                                                |
|--------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
| [`BatchRequestBody`](_autosummary/oa.oa_types.html.md#oa.oa_types.BatchRequestBody)(\*\*data)    |                                                                                |
| [`EmbeddingResponse`](_autosummary/oa.oa_types.html.md#oa.oa_types.EmbeddingResponse)(\*\*data)   |                                                                                |
| [`InputDataJsonL`](_autosummary/oa.oa_types.html.md#oa.oa_types.InputDataJsonL)                |                                                                                |
| [`InputText`](_autosummary/oa.oa_types.html.md#oa.oa_types.InputText)(\*\*data)           | Used to specify the input data in some OpenAI API endpounts.                   |
| [`JsonL`](_autosummary/oa.oa_types.html.md#id0)([root])                 | A generic class for JSONL (JSON Lines) files, which are lists of dictionaries. |
| `JsonL[InputText]`([root])                                                     | A generic class for JSONL (JSON Lines) files, which are lists of dictionaries. |
| [`RequestResponse`](_autosummary/oa.oa_types.html.md#oa.oa_types.RequestResponse)(\*\*data)     |                                                                                |
| [`Response`](_autosummary/oa.oa_types.html.md#id2)(\*\*data)            |                                                                                |
| [`ResponseBody`](_autosummary/oa.oa_types.html.md#oa.oa_types.ResponseBody)(\*\*data)        |                                                                                |
| [`Response[Embedding]`](_autosummary/oa.oa_types.html.md#oa.oa_types.EmbeddingResponse)(\*\*data) |                                                                                |
| [`Usage`](_autosummary/oa.oa_types.html.md#oa.oa_types.Usage)(\*\*data)               |                                                                                |

### *class* oa.oa_types.BatchRequest(\*\*data)

Bases: `BaseModel`

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].

### *class* oa.oa_types.BatchRequestBody(\*\*data)

Bases: `BaseModel`

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].

### *class* oa.oa_types.EmbeddingResponse(\*\*data)

Bases: [`Response`](_autosummary/oa.oa_types.html.md#id2)

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].

### oa.oa_types.InputDataJsonL

alias of `JsonL[InputText]`

### *class* oa.oa_types.InputText(\*\*data)

Bases: `BaseModel`

Used to specify the input data in some OpenAI API endpounts.

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].

### *class* oa.oa_types.JsonL(root=PydanticUndefined, \*\*data)

Bases: `RootModel[list[TypeVar]]`, [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)[`T`]

A generic class for JSONL (JSON Lines) files, which are lists of dictionaries.

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].

### *class* oa.oa_types.JsonL(root=PydanticUndefined, \*\*data)

Bases: `RootModel[list[TypeVar]]`, [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)[`T`]

A generic class for JSONL (JSON Lines) files, which are lists of dictionaries.

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].

### *class* oa.oa_types.RequestResponse(\*\*data)

Bases: `BaseModel`, [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)[`DatumT`]

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].

### *class* oa.oa_types.Response(\*\*data)

Bases: `BaseModel`, [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)[`DatumT`]

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].

### *class* oa.oa_types.Response(\*\*data)

Bases: `BaseModel`, [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)[`DatumT`]

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].

### *class* oa.oa_types.ResponseBody(\*\*data)

Bases: `BaseModel`, [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)[`DatumT`]

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].

### *class* oa.oa_types.Usage(\*\*data)

Bases: `BaseModel`

#### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}*

Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].


# _autosummary/oa.openai_specs.html.md

# oa.openai_specs

Tools to extract specs from the openai interface

See raw schemas by doing

```pycon
>>> from oa.openai_specs import schemas
>>> sorted(schemas)
['AssistantFileObject', 'AssistantObject', 'AssistantToolsCode', 'AssistantToolsFunction', 'AssistantToolsRetrieval', 'ChatCompletionFunctionCallOption',
'ChatCompletionFunctions', 'ChatCompletionMessageToolCall', 'ChatCompletionMessageToolCallChunk', 'ChatCompletionMessageToolCalls',
'ChatCompletionNamedToolChoice', 'ChatCompletionRequestAssistantMessage', 'ChatCompletionRequestFunctionMessage', 'ChatCompletionRequestMessage',
'ChatCompletionRequestMessageContentPart', 'ChatCompletionRequestMessageContentPartImage', 'ChatCompletionRequestMessageContentPartText',
'ChatCompletionRequestSystemMessage', 'ChatCompletionRequestToolMessage', 'ChatCompletionRequestUserMessage', 'ChatCompletionResponseMessage',
'ChatCompletionRole', 'ChatCompletionStreamResponseDelta', 'ChatCompletionTool', 'ChatCompletionToolChoiceOption', 'CompletionUsage',
'CreateAssistantFileRequest', 'CreateAssistantRequest', 'CreateChatCompletionFunctionResponse', 'CreateChatCompletionImageResponse',
'CreateChatCompletionRequest', 'CreateChatCompletionResponse', 'CreateChatCompletionStreamResponse', 'CreateCompletionRequest',
'CreateCompletionResponse', 'CreateEditRequest', 'CreateEditResponse', 'CreateEmbeddingRequest', 'CreateEmbeddingResponse', 'CreateFileRequest',
'CreateFineTuneRequest', 'CreateFineTuningJobRequest', 'CreateImageEditRequest', 'CreateImageRequest', 'CreateImageVariationRequest', 'CreateMessageRequest',
'CreateModerationRequest', 'CreateModerationResponse', 'CreateRunRequest', 'CreateSpeechRequest', 'CreateThreadAndRunRequest', 'CreateThreadRequest',
'CreateTranscriptionRequest', 'CreateTranscriptionResponse', 'CreateTranslationRequest', 'CreateTranslationResponse', 'DeleteAssistantFileResponse',
'DeleteAssistantResponse', 'DeleteFileResponse', 'DeleteMessageResponse', 'DeleteModelResponse', 'DeleteThreadResponse', 'Embedding', 'Error',
'ErrorResponse', 'FineTune', 'FineTuneEvent', 'FineTuningJob', 'FineTuningJobEvent', 'FunctionObject', 'FunctionParameters', 'Image',
'ImagesResponse', 'ListAssistantFilesResponse', 'ListAssistantsResponse', 'ListFilesResponse', 'ListFineTuneEventsResponse', 'ListFineTunesResponse',
'ListFineTuningJobEventsResponse', 'ListMessageFilesResponse', 'ListMessagesResponse', 'ListModelsResponse', 'ListPaginatedFineTuningJobsResponse',
'ListRunStepsResponse', 'ListRunsResponse', 'ListThreadsResponse', 'MessageContentImageFileObject', 'MessageContentTextAnnotationsFileCitationObject',
'MessageContentTextAnnotationsFilePathObject', 'MessageContentTextObject', 'MessageFileObject', 'MessageObject', 'Model', 'ModifyAssistantRequest',
'ModifyMessageRequest', 'ModifyRunRequest', 'ModifyThreadRequest', 'OpenAIFile', 'RunObject', 'RunStepDetailsMessageCreationObject', 'RunStepDetailsToolCallsCodeObject',
'RunStepDetailsToolCallsCodeOutputImageObject', 'RunStepDetailsToolCallsCodeOutputLogsObject', 'RunStepDetailsToolCallsFunctionObject', 'RunStepDetailsToolCallsObject',
'RunStepDetailsToolCallsRetrievalObject', 'RunStepObject', 'RunToolCallObject', 'SubmitToolOutputsRunRequest', 'ThreadObject']
>>> schema = schemas['CreateCompletionRequest']
>>> schema['properties']
 {'model': {'description': 'ID of the model to use...
```

Get resulting signatures by doing.

```pycon
>>> from oa.openai_specs import sig
>>> sig.CreateCompletionRequest)
<Sig (model: str, prompt='<|endoftext|>', *, seed: int, best_of: int = 1, echo: bool = False,
frequency_penalty: float = 0, logit_bias: dict = None, logprobs: int = None, max_tokens: int = None,
n: int = 1, presence_penalty: float = 0, stop=None, stream: bool = False, suffix: str = None,
temperature: float = 1, top_p: float = 1, user: str = None)>
```

Or see argument descriptions in rst format by doing:

```pycon
>>> from oa.openai_specs import schema_to_rst_argument_descriptions, schemas
>>> schema_to_rst_argument_descriptions(schemas['CreateCompletionRequest'])
```

```text
```

### Functions

| [`get_openapi_spec_dict`](_autosummary/oa.openai_specs.html.md#oa.openai_specs.get_openapi_spec_dict)([openapi_spec_url, ...])   | Get the dict of the openapi spec                       |
|---------------------------------------------------------------------------------------------------|--------------------------------------------------------|
| [`merge_keys_to_values`](_autosummary/oa.openai_specs.html.md#oa.openai_specs.merge_keys_to_values)(d[, key_name])              | Merge the keys of a dict into the values of the dict.  |
| [`normalized_file_name`](_autosummary/oa.openai_specs.html.md#oa.openai_specs.normalized_file_name)(prompt)                     | Convert prompt to a normalized valid file/folder name  |
| `prompt_path`(prompt[, prefix])                                                                   |                                                        |
| [`properties_to_annotation`](_autosummary/oa.openai_specs.html.md#oa.openai_specs.properties_to_annotation)(name, props)            | Get annotations from a schema                          |
| [`properties_to_param_dict`](_autosummary/oa.openai_specs.html.md#oa.openai_specs.properties_to_param_dict)(name, props)            | Get all but kind fields of a Parameter object          |
| [`schema_to_docs`](_autosummary/oa.openai_specs.html.md#oa.openai_specs.schema_to_docs)(name, schema[, prefix, ...])      | Get the docs for a schema                              |
| [`schema_to_rst_argument_descriptions`](_autosummary/oa.openai_specs.html.md#oa.openai_specs.schema_to_rst_argument_descriptions)(schema)      | Yield rst-formatted argument descriptions for a schema |
| [`schema_to_signature`](_autosummary/oa.openai_specs.html.md#oa.openai_specs.schema_to_signature)(schema)                      | Get a signature from a schema                          |
| `schemas_df`(schema)                                                                              |                                                        |

### Classes

| [`Message`](_autosummary/oa.openai_specs.html.md#oa.openai_specs.Message)   |    |
|------------------------------------------------------------|----|
| `SpecNames`()                                              |    |

### *class* oa.openai_specs.Message

Bases: [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)

### oa.openai_specs.get_openapi_spec_dict(openapi_spec_url='https://raw.githubusercontent.com/thorwhalen/oa/main/misc/openapi.yaml', , refresh=False, expand_refs=True)

Get the dict of the openapi spec

### oa.openai_specs.merge_keys_to_values(d, key_name='key')

Merge the keys of a dict into the values of the dict.

```pycon
>>> d = {'a': {'b': 1}, 'c': {'d': 2, 'e': 3}}
>>> dict(merge_keys_to_values(d))
{'a': {'key': 'a', 'b': 1}, 'c': {'key': 'c', 'd': 2, 'e': 3}}
```

Useful when, for example, you want to make a table containing both keys and values.

### oa.openai_specs.normalized_file_name(prompt)

Convert prompt to a normalized valid file/folder name

* **Return type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

```pycon
>>> normalized_file_name("This is a prompt")
'this is a prompt'
>>> normalized_file_name("This is: a PROMPT!  (with punctuation)")
'this is a prompt with punctuation'
```

### oa.openai_specs.properties_to_annotation(name, props)

Get annotations from a schema

### oa.openai_specs.properties_to_param_dict(name, props)

Get all but kind fields of a Parameter object

### oa.openai_specs.schema_to_docs(name, schema, prefix='', line_prefix='\\\\t')

Get the docs for a schema

```pycon
>>> from oa.openai_specs import specs
>>> schema = specs['components']['schemas']['CreateChatCompletionRequest']
>>> print(schema_to_docs('chatcompletion', schema))
chatcompletion(...
```

* **Parameters:**
  **model** – ID of the model to use. Currently, only …

### oa.openai_specs.schema_to_rst_argument_descriptions(schema, process_description=<function \_clean_up_whitespace>)

Yield rst-formatted argument descriptions for a schema

```pycon
>>> from oa.openai_specs import specs
>>> schema = specs['components']['schemas']['CreateChatCompletionRequest']
>>> print(*schema_to_rst_argument_descriptions(schema), '\n')
:param model: ID of the model to use. Currently, only ...
```

`process_description` is a function that will be applied to each schema description
(so you can clean it up, or add links, etc.). By default, it will replace all
whitespaces with single space, and strip.

### oa.openai_specs.schema_to_signature(schema)

Get a signature from a schema

```pycon
>>> from oa.openai_specs import specs
>>> schema = specs['components']['schemas']['CreateChatCompletionRequest']
>>> print(str(schema_to_signature(schema)))
(model: str, messages: List[openai_specs.Message], *, temperature: float = 1, ...
```


# _autosummary/oa.stores.html.md

# oa.stores

Data object layers for openai resources

### Functions

| [`date_filter`](_autosummary/oa.stores.html.md#oa.stores.date_filter)(objs[, min_date, max_date, ...])   | Filter objects by date.                                                                                                                                           |
|-------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `ensure_utc_date`(x, \*[, val_if_none])                                                         |                                                                                                                                                                   |
| [`extract_id`](_autosummary/oa.stores.html.md#oa.stores.extract_id)([method, is_id, has_id, get_id])    | Decorator that will extract the id from the first non-instance argument of a method.                                                                              |
| [`get_json_data_from_response`](_autosummary/oa.stores.html.md#oa.stores.get_json_data_from_response)(response)          | Extract the embeddings from a HttpxBinaryResponseContent object                                                                                                   |
| [`get_json_or_jsonl_data`](_autosummary/oa.stores.html.md#oa.stores.get_json_or_jsonl_data)(response)               | Extract the json data from a response                                                                                                                             |
| [`is_task_dict`](_autosummary/oa.stores.html.md#oa.stores.is_task_dict)(x)                                | Is a dict (or Mapping) the schema of an openai API 'task'                                                                                                         |
| [`is_task_dict_list`](_autosummary/oa.stores.html.md#oa.stores.is_task_dict_list)(x)                           | Is a list (or iterable) of dicts (or Mappings) the schema of an openai API 'task'                                                                                 |
| [`object_of_data`](_autosummary/oa.stores.html.md#oa.stores.object_of_data)(data)                           | This function extracts the object (value) from a {object: V, index: i, V} dict which is the format you'll find in the ['response']['body']['data'] of a response. |
| `print_some_jsonl_line_fields`(line)                                                            |                                                                                                                                                                   |
| `response_body_data`(response_dict)                                                             |                                                                                                                                                                   |
| `response_body_data_objects`(response_dict)                                                     |                                                                                                                                                                   |

### Classes

| [`DataObject`](_autosummary/oa.stores.html.md#oa.stores.DataObject)                                    | dicts that have two required fields: 'object' and 'index'                              |
|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`EmbeddingsDataObject`](_autosummary/oa.stores.html.md#oa.stores.EmbeddingsDataObject)                          | A DataObject with object='embeddings' and an 'embeddings' key that is a list of floats |
| [`MappingHooks`](_autosummary/oa.stores.html.md#oa.stores.MappingHooks)()                                |                                                                                        |
| [`MutuableMappingHooks`](_autosummary/oa.stores.html.md#oa.stores.MutuableMappingHooks)()                        |                                                                                        |
| [`OaBatches`](_autosummary/oa.stores.html.md#oa.stores.OaBatches)([client])                           | A key-value store for OpenAI batches metadata.                                         |
| [`OaBatchesBase`](_autosummary/oa.stores.html.md#oa.stores.OaBatchesBase)([client])                       |                                                                                        |
| `OaDacc`([client])                                                                             |                                                                                        |
| [`OaFiles`](_autosummary/oa.stores.html.md#oa.stores.OaFiles)([client, purpose, ...])               | A key-value store for OpenAI files content data.                                       |
| [`OaFilesBase`](_autosummary/oa.stores.html.md#oa.stores.OaFilesBase)([client, purpose, ...])           |                                                                                        |
| [`OaFilesJsonData`](_autosummary/oa.stores.html.md#oa.stores.OaFilesJsonData)([client, purpose, ...])       | A key-value store for OpenAI files content data.                                       |
| [`OaFilesMetadata`](_autosummary/oa.stores.html.md#oa.stores.OaFilesMetadata)([client, purpose, ...])       | A key-value store for OpenAI files metadata.                                           |
| [`OaJsonFiles`](_autosummary/oa.stores.html.md#oa.stores.OaJsonFiles)([client, purpose, ...])           | A key-value store for OpenAI files content data.                                       |
| [`OaJsonLFiles`](_autosummary/oa.stores.html.md#oa.stores.OaJsonLFiles)([client, purpose, ...])          | A key-value store for OpenAI files content data.                                       |
| [`OaMapping`](_autosummary/oa.stores.html.md#oa.stores.OaMapping)()                                   |                                                                                        |
| `OaStores`([client])                                                                           |                                                                                        |
| [`OaVectorStoreFiles`](_autosummary/oa.stores.html.md#oa.stores.OaVectorStoreFiles)(vector_store_id[, client]) | Mapping interface for files within a vector store.                                     |
| [`OaVectorStores`](_autosummary/oa.stores.html.md#oa.stores.OaVectorStores)([client])                      | A key-value store for OpenAI vector stores.                                            |
| [`OaVectorStoresBase`](_autosummary/oa.stores.html.md#oa.stores.OaVectorStoresBase)([client])                  | Base class for OpenAI vector stores mapping interface.                                 |
| [`ResponseDict`](_autosummary/oa.stores.html.md#oa.stores.ResponseDict)                                  |                                                                                        |

### *class* oa.stores.DataObject

Bases: [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)

dicts that have two required fields: ‘object’ and ‘index’

### *class* oa.stores.EmbeddingsDataObject

Bases: [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)

A DataObject with object=’embeddings’ and an ‘embeddings’ key that is a list of
floats

### *class* oa.stores.MappingHooks

Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)

### *class* oa.stores.MutuableMappingHooks

Bases: [`MappingHooks`](_autosummary/oa.stores.html.md#oa.stores.MappingHooks)

### *class* oa.stores.OaBatches(client=None, \*\*extra_kwargs)

Bases: `Store`

A key-value store for OpenAI batches metadata.
Keys are the batch IDs.

#### append(input_file_id, , endpoint='/v1/embeddings', completion_window='24h', metadata=None)

Create and submit a new batch via submitting the input file (obj or id).

#### metadata(batch_id)

Retrieve metadata for a batch.

* **Return type:**
  `Batch`

### *class* oa.stores.OaBatchesBase(client=None, \*\*extra_kwargs)

Bases: [`OaMapping`](_autosummary/oa.stores.html.md#oa.stores.OaMapping)

#### append(input_file_id, , endpoint='/v1/embeddings', completion_window='24h', metadata=None)

Create and submit a new batch via submitting the input file (obj or id).

#### metadata(batch_id)

Retrieve metadata for a batch.

* **Return type:**
  `Batch`

### *class* oa.stores.OaFiles(client=None, purpose='batch', iter_filter_purpose=False, encoding='utf-8', \*, file, expires_after=<openai.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)

Bases: `Store`

A key-value store for OpenAI files content data.
Keys are the file IDs.

### *class* oa.stores.OaFilesBase(client=None, purpose='batch', iter_filter_purpose=False, encoding='utf-8', \*, file, expires_after=<openai.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)

Bases: [`OaMapping`](_autosummary/oa.stores.html.md#oa.stores.OaMapping)

### *class* oa.stores.OaFilesJsonData(client=None, purpose='batch', iter_filter_purpose=False, encoding='utf-8', \*, file, expires_after=<openai.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)

Bases: `Store`

A key-value store for OpenAI files content data.
Keys are the file IDs.
Values are the data extracted from the HttpxBinaryResponseContent object.

### *class* oa.stores.OaFilesMetadata(client=None, purpose='batch', iter_filter_purpose=False, encoding='utf-8', \*, file, expires_after=<openai.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)

Bases: [`OaFilesBase`](_autosummary/oa.stores.html.md#oa.stores.OaFilesBase)

A key-value store for OpenAI files metadata.

### *class* oa.stores.OaJsonFiles(client=None, purpose='batch', iter_filter_purpose=False, encoding='utf-8', \*, file, expires_after=<openai.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)

Bases: `Store`

A key-value store for OpenAI files content data.
Keys are the file IDs.

### *class* oa.stores.OaJsonLFiles(client=None, purpose='batch', iter_filter_purpose=False, encoding='utf-8', \*, file, expires_after=<openai.Omit object>, extra_headers=None, extra_query=None, extra_body=None, timeout=NOT_GIVEN)

Bases: `Store`

A key-value store for OpenAI files content data.
Keys are the file IDs.

### *class* oa.stores.OaMapping

Bases: [`MappingHooks`](_autosummary/oa.stores.html.md#oa.stores.MappingHooks), `KvReader`

### *class* oa.stores.OaVectorStoreFiles(vector_store_id, client=None, \*\*extra_kwargs)

Bases: [`OaMapping`](_autosummary/oa.stores.html.md#oa.stores.OaMapping)

Mapping interface for files within a vector store.

#### add_file(file_id)

Add file to vector store.

* **Return type:**
  [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)

#### metadata(file_id)

Get file info from vector store.

* **Return type:**
  [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)

### *class* oa.stores.OaVectorStores(client=None, \*\*extra_kwargs)

Bases: `Store`

A key-value store for OpenAI vector stores.
Keys are the vector store IDs.

#### create(name, \*\*config)

Create a new vector store with given name.

* **Return type:**
  [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)

#### get_by_name(name)

Get vector store by name (since OpenAI API doesn’t support this directly).

#### metadata(vs_id)

Get vector store metadata by ID.

* **Return type:**
  [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)

### *class* oa.stores.OaVectorStoresBase(client=None, \*\*extra_kwargs)

Bases: [`OaMapping`](_autosummary/oa.stores.html.md#oa.stores.OaMapping)

Base class for OpenAI vector stores mapping interface.

#### create(name, \*\*config)

Create a new vector store with given name.

* **Return type:**
  [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)

#### get_by_name(name)

Get vector store by name (since OpenAI API doesn’t support this directly).

#### metadata(vs_id)

Get vector store metadata by ID.

* **Return type:**
  [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)

### *class* oa.stores.ResponseDict

Bases: [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)

### oa.stores.date_filter(objs, min_date=None, max_date=None, , date_extractor='created_at', stop_on_first_out_of_range=False)

Filter objects by date.

* **Parameters:**
  * **objs** – The objects to filter (must have a)
  * **min_date** (`Union`[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`int`](https://docs.python.org/3/builtins/functions.html#int), [`None`](https://docs.python.org/3/builtins/constants.html#None)]) – The minimum date (inclusive)
  * **max_date** (`Union`[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`int`](https://docs.python.org/3/builtins/functions.html#int), [`None`](https://docs.python.org/3/builtins/constants.html#None)]) – The maximum date (inclusive)
  * **date_attr** – The attribute to get the date from
  * **stop_on_first_out_of_range** – If True, stop iteration on first out-of-range date

### oa.stores.extract_id(method=None, \*, is_id=<function \_is_string>, has_id=<function \_has_id_attr>, get_id=operator.attrgetter('id'))

Decorator that will extract the id from the first non-instance argument of a method.

```pycon
>>> @extract_id
... def veni(self, vidi, vici):
...     return f"{vidi=}, {vici=}"
>>> assert (
...     veni(None, 'hi', vici=3)  # calling the function
...     == veni.__wrapped__(None, 'hi', vici=3)  # outputs the same as calling the original
...     == "vidi='hi', vici=3"
... )
```

Except it now has extra powers; if your id is contained in a attribute,
it’ll be extracted.

```pycon
>>> from types import SimpleNamespace
>>> obj = SimpleNamespace(id='hi')
>>> obj.id
'hi'
>>> assert veni(None, obj, vici=3) == "vidi='hi', vici=3"
```

You can also customize the filters and the id getter.
The following will resolve a string representation of an integer as an id.

```pycon
>>> @extract_id(is_id=lambda x: isinstance(x, int), has_id=str.isnumeric, get_id=int)
... def add_one(self, x):
...     return x
...
>>> assert add_one(None, 3) == 3
>>> assert add_one(None, "42") == 42
```

### oa.stores.get_json_data_from_response(response)

Extract the embeddings from a HttpxBinaryResponseContent object

* **Return type:**
  [*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)

### oa.stores.get_json_or_jsonl_data(response)

Extract the json data from a response

### oa.stores.is_task_dict(x)

Is a dict (or Mapping) the schema of an openai API ‘task’

### oa.stores.is_task_dict_list(x)

Is a list (or iterable) of dicts (or Mappings) the schema of an openai API ‘task’

### oa.stores.object_of_data(data)

This function extracts the object (value) from a {object: V, index: i, V} dict
which is the format you’ll find in the [‘response’][‘body’][‘data’] of a response.

* **Return type:**
  [`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`DataObjectValue`)

```pycon
>>> object_of_data({'object': 'embeddings', 'index': 3, 'embeddings': [1, 2, 3]})
[1, 2, 3]
```


# _autosummary/oa.tools.html.md

# oa.tools

Interface tools

### Functions

| [`constrained_answer`](_autosummary/oa.tools.html.md#oa.tools.constrained_answer)(prompt, valid_answers, \*)    | Get an answer from the LLM constrained to a set of valid answers or types.                                                                       |
|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `dflt_factory_key`(f)                                                                             |                                                                                                                                                  |
| `dflt_function_key`(f)                                                                            |                                                                                                                                                  |
| [`ensure_json_type`](_autosummary/oa.tools.html.md#oa.tools.ensure_json_type)(json_type)                      | Ensure that the json type is a string that is a valid json type                                                                                  |
| `extract_parts`(string, pattern)                                                                  |                                                                                                                                                  |
| `identity`(x)                                                                                     |                                                                                                                                                  |
| [`infer_schema_from_verbal_description`](_autosummary/oa.tools.html.md#oa.tools.infer_schema_from_verbal_description)(...[, ...]) | Infer a JSON Schema (`{name, properties, type}`) from a verbal description.                                                                      |
| [`make_generic_json_schema`](_autosummary/oa.tools.html.md#oa.tools.make_generic_json_schema)(json_type)              | Make a generic json schema for a given json type.                                                                                                |
| [`pattern_based_map`](_autosummary/oa.tools.html.md#oa.tools.pattern_based_map)(func, string, pattern[, ...])  | Applies a function to parts of the string that are either matching or non-matching based on a regex pattern, depending on the value of apply_to. |
| [`prompt_function`](_autosummary/oa.tools.html.md#oa.tools.prompt_function)(template, \*[, defaults, ...])   | Convert a string template to a function that will produce a prompt string and ask an LLM (`prompt_func`) to respond to it.                       |
| [`prompt_json_function`](_autosummary/oa.tools.html.md#oa.tools.prompt_json_function)(template[, ...])            | Make prompt functions that return jsons (dicts) with a given schema.                                                                             |
| [`remove_pattern`](_autosummary/oa.tools.html.md#oa.tools.remove_pattern)(string[, pattern_to_remove])      | Returns a where a given regular expression pattern has been removed.                                                                             |
| `string_format_embodier`(template, \*[, ...])                                                     |                                                                                                                                                  |

### Classes

| [`JsonTypes`](_autosummary/oa.tools.html.md#oa.tools.JsonTypes)(\*values)                              |                           |
|---------------------------------------------------------------------------------------------------|---------------------------|
| [`PromptFuncs`](_autosummary/oa.tools.html.md#oa.tools.PromptFuncs)([template_store, function_key, ...]) | Make AI enabled functions |

### *class* oa.tools.JsonTypes(\*values)

Bases: [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum)

### *class* oa.tools.PromptFuncs(template_store='/home/runner/work/oa/oa/oa/data/templates/chatgpt:.txt, ', \*, function_key=<function <lambda>>, factory_key=<function <lambda>>, factories=(('.txt', <function prompt_function>), ('', <function prompt_function>)), extra_template_kwargs=None)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Make AI enabled functions

#### funcs_and_sigs()

Return a mapping of function names to signatures

#### print_signatures()

Print signatures of all functions

#### reload()

Reload all functions

### oa.tools.constrained_answer(prompt, valid_answers, , model='gpt-4o-mini', n=1)

Get an answer from the LLM constrained to a set of valid answers or types.

Uses `prompt_json_function` to ensure the LLM returns a valid response based on
constraints.

This can be seen as a facade for some common structured output use cases, as well
as a convenient tool to do response statistics and validation (via n>1).

* **Parameters:**
  * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The question or prompt to ask the LLM
  * **valid_answers** (`Union`[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`int`](https://docs.python.org/3/builtins/functions.html#int)], [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`float`](https://docs.python.org/3/builtins/functions.html#float)], [`type`](https://docs.python.org/3/builtins/functions.html#type), [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`float`](https://docs.python.org/3/builtins/functions.html#float), [`float`](https://docs.python.org/3/builtins/functions.html#float)]]) – 

    Can be:
    - list[str]: List of valid string options
    - list[int]: List of valid integer options
    - list[float]: List of valid float options
    - bool: Constrains answer to True or False
    - int: Any integer
    - float: Any number
    - tuple[float, float]: Numerical range (min, max) inclusive
  * **model** – The model to use for the LLM (default: “gpt-4o-mini”)
  * **n** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Number of times to call the LLM (default: 1)
* **Returns:**
  One of the valid answers, respecting the type constraint

### Examples

```pycon
>>> # String options
>>> answer = constrained_answer(
...     "Is Python compiled or interpreted?",
...     ["compiled", "interpreted", "both"]
... )
>>> answer in ["compiled", "interpreted", "both"]
True
```

```pycon
>>> # Boolean
>>> answer = constrained_answer(
...     "Is Python dynamically typed?",
...     bool
... )
>>> isinstance(answer, bool)
True
```

```pycon
>>> # Integer options
>>> answer = constrained_answer(
...     "How many wheels does a car have?",
...     [2, 3, 4, 6, 8]
... )
>>> answer in [2, 3, 4, 6, 8]
True
```

```pycon
>>> # Numerical range
>>> answer = constrained_answer(
...     "What is a reasonable hourly rate for a senior Python developer? (USD)",
...     (50.0, 300.0)
... )
>>> 50.0 <= answer <= 300.0
True
```

### oa.tools.ensure_json_type(json_type)

Ensure that the json type is a string that is a valid json type

* **Return type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

```pycon
>>> ensure_json_type('string')
'string'
>>> ensure_json_type(str)
'string'
>>> ensure_json_type(object)
Traceback (most recent call last):
...
ValueError: Cannot convert ...
```

### oa.tools.infer_schema_from_verbal_description(verbal_description, \*, prompt_func=<function chat>, prompt_func_kwargs=None, model='gpt-4o-mini')

Infer a JSON Schema (`{name, properties, type}`) from a verbal description.

The LLM backend is **injectable** so this is not hardwired to OpenAI: pass any
`prompt_func` with the `(prompt, **kwargs) -> str` shape (e.g. a
provider-agnostic `aix.chat`) to route the inference through a different
provider, optionally pinning `model` / extra `prompt_func_kwargs`. The
defaults preserve the original behavior (oa’s `chat` on `gpt-4o-mini`).

* **Parameters:**
  * **verbal_description** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Natural-language description of the desired JSON output.
  * **prompt_func** – The LLM callable to use (default: oa’s `chat`). Forwarded to
    [`prompt_json_function()`](_autosummary/oa.tools.html.md#oa.tools.prompt_json_function).
  * **prompt_func_kwargs** – Extra keyword arguments merged into the `prompt_func`
    call (e.g. provider options).
  * **model** – Model id passed to `prompt_func` (pass `None` to let an
    `aix`-style backend resolve its own configured default).
* **Returns:**
  A `dict` with at least `name` and `properties` keys (the inferred
  JSON Schema, formatted for OpenAI “JSON mode”).

### oa.tools.make_generic_json_schema(json_type)

Make a generic json schema for a given json type.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

```pycon
>>> make_generic_json_schema('string')
{'name': 'generic_string_schema', 'schema': {'properties': {'result': {'type': 'string'}}, 'required': ['result']}}
```

### oa.tools.pattern_based_map(func, string, pattern, apply_to='unmatched')

Applies a function to parts of the string that are either matching or non-matching based on a regex pattern,
depending on the value of apply_to.

### Example

```pycon
>>> func = str.upper
>>> string = "the good the ```bad``` and the ugly"
>>> ignore_pattern = r'```.*?```'
>>> pattern_based_map(func, string, ignore_pattern)
'THE GOOD THE ```bad``` AND THE UGLY'
>>> pattern_based_map(func, string, ignore_pattern, 'matched')
'the good the ```BAD``` and the ugly'
```

### oa.tools.prompt_function(template, \*, defaults=None, template_to_names=<function \_extract_names_from_format_string>, template_to_defaults=<function \_extract_defaults_from_format_string>, embodier=<function string_format_embodier>, arg_kinds=None, name='prompt', prompt_func=<function chat>, prompt_func_kwargs=None, ingress=None, egress=None, doc='The function composes a prompt and asks an LLM to respond to it.', module='oa.tools')

Convert a string template to a function that will produce a prompt string
and ask an LLM (`prompt_func`) to respond to it.

* **Parameters:**
  * **template** – A string template with placeholders.
  * **defaults** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – A dictionary of default values for placeholders.
  * **template_to_names** ([`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)) – A function that extracts names from a template.
  * **template_to_defaults** ([`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)) – A function that extracts defaults from a template.
  * **embodier** ([`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)) – A function that converts a template to a function that will
    produce a prompt string.
  * **arg_kinds** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – A dictionary of argument kinds for the function.
  * **name** – The name of the function.
  * **prompt_func** – The function that will be used to ask the LLM to respond to
    the prompt. If None, the output function will only produce the prompt string,
    not ask the LLM to respond to it.
  * **prompt_func_kwargs** – Keyword arguments to pass to `prompt_func`.
  * **ingress** – A function to apply to the input of `prompt_func`.
  * **egress** – A function to apply to the output of `prompt_func`.
  * **doc** – The docstring of the function.
  * **module** – The module of the function.

In the following example, we’ll use the `prompt_func=None` argument to get a
function that simply injects inputs in a prompt template, without actually calling
an AI-enabled `prompt_func`.
Note in this example, how a block of the prompt template string is ignored for
injection purposes, via a triple-backtick marker.

```pycon
>>> prompt_template = '''
... ```
... In this block, all {placeholders} are {igno:red} so that they can appear in prompt.
... ```
... But outside {inputs} are {injected:normally}
... '''
>>> f = prompt_function(prompt_template, prompt_func=None)
>>> from inspect import signature
>>> assert str(signature(f)) == "(inputs, *, injected='normally')"
>>> print(f('INPUTS', injected="INJECTED"))
```

```text
In this block, all {placeholders} are {igno:red} so that they can appear in prompt.
```

But outside INPUTS are INJECTED

### oa.tools.prompt_json_function(template, json_schema='string', \*, defaults=None, embodier=<function string_format_embodier>, arg_kinds=None, name='prompt', prompt_func=<function chat>, prompt_func_kwargs=None, model='gpt-4o-mini', ingress=None, egress=None, doc='The function composes a prompt and asks an LLM to respond to it with json.', module='oa.tools')

Make prompt functions that return jsons (dicts) with a given schema.

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

### oa.tools.remove_pattern(string, pattern_to_remove=re.compile('\`\`\`.\*?\`\`\`', re.DOTALL))

Returns a where a given regular expression pattern has been removed.

```pycon
>>> string = 'this ```is a``` string ```with several``` backticks'
>>> remove_pattern(string)
'this  string  backticks'
```


# _autosummary/oa.util.html.md

# oa.util

oa utils

### Functions

| [`chunk_iterable`](_autosummary/oa.util.html.md#oa.util.chunk_iterable)(iterable, chk_size, \*[, ...])   | Divide an iterable into chunks/batches of a specific size.                                                                                                   |
|--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`concat_lists`](_autosummary/oa.util.html.md#oa.util.concat_lists)(lists)                             | Concatenate a list of lists into a single list.                                                                                                              |
| [`ensure_oa_client`](_autosummary/oa.util.html.md#oa.util.ensure_oa_client)(oa_client)                     | Ensure that an OpenAI client is available, either by using the provided one or creating a new one.                                                           |
| [`ensure_openai_api_key`](_autosummary/oa.util.html.md#oa.util.ensure_openai_api_key)()                         | Make sure the module-level `openai` client has an API key, resolving it lazily.                                                                              |
| [`get_api_key_from_config`](_autosummary/oa.util.html.md#oa.util.get_api_key_from_config)()                       | The OpenAI API key: oa's config store, then the environment, then ask the user.                                                                              |
| [`get_package_name`](_autosummary/oa.util.html.md#oa.util.get_package_name)()                              | Return current package name                                                                                                                                  |
| [`iso_date_to_utc_int`](_autosummary/oa.util.html.md#oa.util.iso_date_to_utc_int)(iso_date)                   | Convert iso date string to utc integer timestamp.                                                                                                            |
| [`jsonl_dumps`](_autosummary/oa.util.html.md#oa.util.jsonl_dumps)(x[, encoding])                      | Serialize an iterable as JSONL bytes                                                                                                                         |
| [`jsonl_loads_iter`](_autosummary/oa.util.html.md#oa.util.jsonl_loads_iter)(src, \*[, get_lines, ...])     | Deserialize JSONL bytes into a python iterable (dict or list of dicts)                                                                                       |
| `kv_strip_value`(k, v)                                                                           |                                                                                                                                                              |
| `merge_multiple_signatures`(iterable_of_sigs, ...)                                               |                                                                                                                                                              |
| `mk_client`([api_key])                                                                           |                                                                                                                                                              |
| [`mk_local_files_saves_callback`](_autosummary/oa.util.html.md#oa.util.mk_local_files_saves_callback)([rootdir, ...])   | Returns a function that takes two inputs (i: int, obj: Any) and saves the serializer(obj) bytes in a file named index_to_filename(i) in the rootdir.         |
| `mk_template_store`(template_store)                                                              |                                                                                                                                                              |
| [`num_tokens`](_autosummary/oa.util.html.md#oa.util.num_tokens)([text, model])                       | Return the number of tokens in a string, under given model.                                                                                                  |
| [`oa_extractors_obj`](_autosummary/oa.util.html.md#oa.util.oa_extractors_obj)(\*\*named_paths)              | Return a SimpleNamespace of extractors for the named paths                                                                                                   |
| [`pricing_info`](_autosummary/oa.util.html.md#oa.util.pricing_info)([category, print_data_date])       | Return the pricing info for the OpenAI API.                                                                                                                  |
| [`save_in_temp_dir`](_autosummary/oa.util.html.md#oa.util.save_in_temp_dir)(obj[, serializer])             | Saves obj in a temp file, using serializer to serialize it, and returns its path.                                                                            |
| [`source_parameter_props_from`](_autosummary/oa.util.html.md#oa.util.source_parameter_props_from)(parameters)         | A decorator that will change the annotation and default of the parameters of the decorated function, sourcing them from `parameters`, matching them by name. |
| `transpose_and_concatenate`(iterable_of_tuples)                                                  |                                                                                                                                                              |
| `transpose_iterable`(iterable_of_tuples)                                                         |                                                                                                                                                              |
| [`utc_int_to_iso_date`](_autosummary/oa.util.html.md#oa.util.utc_int_to_iso_date)(utc_time)                   | Convert utc integer timestamp to more human readable iso format.                                                                                             |

### Classes

| [`ProcessingManager`](_autosummary/oa.util.html.md#oa.util.ProcessingManager)(pending_items, ...[, ...])   | A class to manage and monitor the processing of a collection of items, allowing customizable processing functions, status handling, and timing control, using keys to track items.   |
|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

### Exceptions

| [`OpenAIKeyNotFoundError`](_autosummary/oa.util.html.md#oa.util.OpenAIKeyNotFoundError)   | No OpenAI API key is configured, and there is no one to ask for it.   |
|---------------------------------------------------------------------------|-----------------------------------------------------------------------|

### *exception* oa.util.OpenAIKeyNotFoundError

Bases: `ConfigNotFound`

No OpenAI API key is configured, and there is no one to ask for it.

### *class* oa.util.ProcessingManager(pending_items, processing_function, handle_status_function, wait_time_function, status_check_interval=5.0, max_cycles=None, completed_items=<factory>, cycles=0)

Bases: [`Generic`](https://docs.python.org/3/library/typing.html#typing.Generic)[`KT`, `VT`, `Result`]

A class to manage and monitor the processing of a collection of items, allowing customizable
processing functions, status handling, and timing control, using keys to track items.

**Use Case**:

- Ideal for scenarios where you have a set of items identified by keys that require periodic status
  checks until they reach a completed state.
- Useful for managing batch jobs, asynchronous tasks, or any operations where items may not complete
  processing immediately.

**Attributes**:

- **pending_items** (`MutableMapping[KT, VT]`): The mapping of keys to pending items.
  : - If an iterable is provided, it is converted to a dict using `dict(enumerate(iterable))`.
- **processing_function** (`Callable[[VT], Tuple[Status, Result]]`): A function that takes a value (item)
  and returns a tuple of `(status, result)`.
  > - `status` (`Status`): Indicates the current state of the item (e.g., `'completed'`, `'in_progress'`, `'failed'`).
  > - `result` (`Result`): Additional data or context about the item’s processing result.
- **handle_status_function** (`Callable[[VT, Status, Result], bool]`): A function that decides whether to remove
  an item from `pending_items` based on its `status` and `result`.
  > - Returns `True` if the item should be removed (e.g., processing is complete or failed irrecoverably).
- **wait_time_function** (`Callable[[float, Dict], float]`): A function that determines how long to wait
  before the next processing cycle.
  > - Takes `cycle_duration` (time taken for the last cycle) and `locals()` dictionary as inputs.
  > - Returns the sleep time in seconds.
- **status_check_interval** (`float`): Desired minimum time (in seconds) between status checks. Defaults to `5.0`.
- **max_cycles** (`Optional[int]`): Maximum number of processing cycles to perform. If `None`, there is no limit.
- **completed_items** (`MutableMapping[KT, Result]`): Mapping of keys to results for items that have been processed.
- **cycles** (`int`): Number of processing cycles that have been performed.

#### process_items()

Runs the processing loop until all pending items are processed or max_cycles is reached.

In each cycle:

- Calls `process_pending_items()` to process the current pending items.
- Increments the cycle count.
- Calculates the duration of the cycle and determines how long to sleep before the next cycle
  using `wait_time_function`.
- Sleeps for the calculated duration if there are still pending items.

The loop continues until:

- `pending_items` is empty (all items have been processed), or
- The number of cycles reaches `max_cycles`, if specified.

#### process_pending_items()

Processes the pending items once.

This method iterates over each key-value pair in `pending_items`, applies the `processing_function`
to determine its status, and then uses `handle_status_function` to decide whether to
remove the item from `pending_items`. Items removed are added to `completed_items` with their results.

#### *property* status *: [bool](https://docs.python.org/3/builtins/functions.html#bool)*

Indicates whether all pending items have been processed.

* **Returns:**
  `True` if there are no more pending items, `False` otherwise.
* **Return type:**
  [*bool*](https://docs.python.org/3/builtins/functions.html#bool)

### oa.util.chunk_iterable(iterable, chk_size, , chunk_type=None)

Divide an iterable into chunks/batches of a specific size.

Handles both mappings (e.g. dicts) and non-mappings (lists, tuples, sets…)
as you probably expect it to (if you give a dict input, it will chunk on the
(key, value) items and return dicts of these).
Thought note that you always can control the type of the chunks with the
`chunk_type` argument.

* **Parameters:**
  * **iterable** ([`Iterable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`T`)] | [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`KT`), [`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`VT`)]) – The iterable or mapping to divide.
  * **chk_size** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – The size of each chunk.
  * **chunk_type** ([`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis), [`Iterable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`T`)] | [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`KT`), [`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`VT`)]] | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – The type of the chunks (list, tuple, set, dict…).
* **Return type:**
  [`Iterator`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`T`)] | [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`T`), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] | [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`KT`), [`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`VT`)]]
* **Returns:**
  An iterator of dicts if the input is a Mapping, otherwise an iterator
  of collections (list, tuple, set…).

### Examples

```pycon
>>> list(chunk_iterable([1, 2, 3, 4, 5], 2))
[[1, 2], [3, 4], [5]]
```

```pycon
>>> list(chunk_iterable((1, 2, 3, 4, 5), 3, chunk_type=tuple))
[(1, 2, 3), (4, 5)]
```

```pycon
>>> list(chunk_iterable({"a": 1, "b": 2, "c": 3}, 2))
[{'a': 1, 'b': 2}, {'c': 3}]
```

```pycon
>>> list(chunk_iterable({"x": 1, "y": 2, "z": 3}, 1, chunk_type=dict))
[{'x': 1}, {'y': 2}, {'z': 3}]
```

### oa.util.concat_lists(lists)

Concatenate a list of lists into a single list.

```pycon
>>> concat_lists([[1, 2], [3, 4], [5, 6]])
[1, 2, 3, 4, 5, 6]
```

### oa.util.ensure_oa_client(oa_client)

Ensure that an OpenAI client is available, either by using the provided one or creating a new one.

* **Return type:**
  `OpenAI`

### oa.util.ensure_openai_api_key()

Make sure the module-level `openai` client has an API key, resolving it lazily.

The key is looked up (config store, environment, then asking the user) the
first time something needs it, never at `import oa` time, so importing
`oa` works – and dependents’ test suites can run – when no key is set.
Resolution follows oa’s own order (store before environment), as when the key
was set at import, and happens once: a key set on `openai.api_key`
afterwards is respected. If no key is stored or in the environment, a key
already set on `openai.api_key` is kept rather than asking the user.
Thread-safe.

* **Return type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

### oa.util.get_api_key_from_config()

The OpenAI API key: oa’s config store, then the environment, then ask the user.

Asking only happens when the user can be asked (see `_can_prompt_user`);
otherwise an informative `OpenAIKeyNotFoundError` is raised. Thread-safe: when
several threads need the key at once, only one asks, and the others reuse the answer.

### oa.util.get_package_name()

Return current package name

### oa.util.iso_date_to_utc_int(iso_date)

Convert iso date string to utc integer timestamp.
Inverse of utc_int_to_iso_date.

* **Return type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

```pycon
>>> iso_date_to_utc_int('2024-08-12T14:01:57+00:00')
1723471317
```

### oa.util.jsonl_dumps(x, encoding='utf-8')

Serialize an iterable as JSONL bytes

* **Return type:**
  [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes)

```pycon
>>> jsonl_dumps([{'a': 1}, {'b': 2}])
b'{"a": 1}\n{"b": 2}'
```

### oa.util.jsonl_loads_iter(src, \*, get_lines=<method 'splitlines' of 'bytes' objects>, line_egress=operator.methodcaller('strip'))

Deserialize JSONL bytes into a python iterable (dict or list of dicts)

* **Return type:**
  [`Iterable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)]

```pycon
>>> list(jsonl_loads(b'\n{"a": 1}\n\n{"b": 2}'))
[{'a': 1}, {'b': 2}]
```

### oa.util.mk_local_files_saves_callback(rootdir=None, \*, serializer=<built-in function dumps>, index_to_filename=<built-in method format of str object>, print_dir_path=True)

Returns a function that takes two inputs (i: int, obj: Any) and saves the
serializer(obj) bytes in a file named index_to_filename(i) in the rootdir.
If rootdir, a temp dir is used.

### oa.util.num_tokens(text=None, model='gpt-3.5-turbo')

Return the number of tokens in a string, under given model.

keywords: token count, number of tokens

* **Return type:**
  [`int`](https://docs.python.org/3/builtins/functions.html#int)

### oa.util.oa_extractors_obj(\*\*named_paths)

Return a SimpleNamespace of extractors for the named paths

### oa.util.pricing_info(category=None, , print_data_date=False)

Return the pricing info for the OpenAI API.

#### NOTE
These are not live prices. Live prices can be found here:

The information pricing_info returns is taken from the file `openai_api_pricing_info.json`
in the `data` directory of the package.
To print a message with the data date, do `pricing_info(print_data_date=True)`.

### oa.util.save_in_temp_dir(obj, serializer=<built-in function dumps>)

Saves obj in a temp file, using serializer to serialize it, and returns its path.

### oa.util.source_parameter_props_from(parameters)

A decorator that will change the annotation and default of the parameters of the
decorated function, sourcing them from `parameters`, matching them by name.

### oa.util.utc_int_to_iso_date(utc_time)

Convert utc integer timestamp to more human readable iso format.
Inverse of iso_date_to_utc_int.

* **Return type:**
  [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)

```pycon
>>> utc_int_to_iso_date(1723471317)
'2024-08-12T14:01:57+00:00'
```


# _autosummary/oa.vector_stores.html.md

# oa.vector_stores

Vector stores and search

### Functions

| [`bind_and_modify`](_autosummary/oa.vector_stores.html.md#oa.vector_stores.bind_and_modify)(func, \*bound_args[, ...])         | Convenience function that both binds arguments and modifies signature.       |
|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| [`docs_to_search_func_factory_via_vector_store`](_autosummary/oa.vector_stores.html.md#oa.vector_stores.docs_to_search_func_factory_via_vector_store)(docs) | Factory function that creates a search function via vector store.            |
| [`docs_to_vector_store`](_autosummary/oa.vector_stores.html.md#oa.vector_stores.docs_to_vector_store)(docs[, vs_name, client])      | Create an OpenAI vector store from a mapping of documents.                   |
| [`mk_search_func_for_oa_vector_store`](_autosummary/oa.vector_stores.html.md#oa.vector_stores.mk_search_func_for_oa_vector_store)(...[, ...])     | Create a search function for an OpenAI vector store using the Responses API. |

### oa.vector_stores.bind_and_modify(func, \*bound_args, \_param_changes=(), \*\*bound_kwargs)

Convenience function that both binds arguments and modifies signature.

This is perfect for your vector store search use case.

* **Parameters:**
  * **func** – The function to wrap
  * **bound_args** – Positional arguments to bind
  * **bound_kwargs** – Dict of argument names to values to bind
  * **\_param_changes** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Parameter modifications
* **Returns:**
  Wrapped function with bound arguments and modified signature

Example for your vector store case:

```pycon
>>> def search(vector_store_id, *, query, filters=None, max_results=10):
...     return f"Searching {vector_store_id} for '{query}'"
>>>
>>> # Bind vector_store_id and make query positional
>>> bound_search = bind_and_modify(
...     search,
...     vector_store_id='my_store',
...     _param_changes=dict(query={'kind': Parameter.POSITIONAL_OR_KEYWORD}),
... )
>>>
>>> bound_search('my query')
"Searching my_store for 'my query'"
```

### oa.vector_stores.docs_to_search_func_factory_via_vector_store(docs)

Factory function that creates a search function via vector store.
This can be used with check_search_func_factory.

* **Return type:**
  [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`Iterable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]]

### oa.vector_stores.docs_to_vector_store(docs, vs_name=None, , client=None)

Create an OpenAI vector store from a mapping of documents.

* **Parameters:**
  * **docs** ([`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]) – Mapping of document keys to text content
  * **vs_name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Optional name for the vector store. If None, generates a unique name.
* **Returns:**
  (vector_store_id, file_id_to_doc_key_mapping)
* **Return type:**
  [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]]

If anything fails after the vector store is created, the store and the files
uploaded so far are deleted (best effort) before the error is re-raised.

### oa.vector_stores.mk_search_func_for_oa_vector_store(vector_store_id, doc_id_mapping=None, , client=None)

Create a search function for an OpenAI vector store using the Responses API.

* **Parameters:**
  * **vector_store_id** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The ID of the vector store to search
  * **doc_id_mapping** ([`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]) – Optional mapping from file IDs to document keys for result translation
* **Return type:**
  [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`Iterable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]]
* **Returns:**
  A function that takes a query and returns search results


# about-this-build.html.md

<!-- generated by epythet -->

# About this build

This documentation was built on **2026-10-14 00:42 UTC** from commit <a href="https://github.com/thorwhalen/oa/commit/617693d165626d37fa9fba8df44e332d2758d202"><code>617693d</code></a> on branch <code>main</code>, for **oa 0.1.60** (from <code>pyproject.toml</code>).

#### NOTE
Nothing suggests a mismatch: the tree was clean at the commit above, and the documented version is the one on PyPI.

## Source

|                     |                                                                                                                                                      |
|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| Commit              | <a href="https://github.com/thorwhalen/oa/commit/617693d165626d37fa9fba8df44e332d2758d202"><code>617693d165626d37fa9fba8df44e332d2758d202</code></a> |
| Branch              | <code>main</code>                                                                                                                                    |
| Tags at this commit | <code>0.1.60</code>                                                                                                                                  |
| Working tree        | clean                                                                                                                                                |
| Remote              | <code>https://github.com/thorwhalen/oa</code>                                                                                                        |

## Continuous integration

|              |                                                                                            |
|--------------|--------------------------------------------------------------------------------------------|
| Repository   | <code>thorwhalen/oa</code>                                                                 |
| Run          | <a href="https://github.com/thorwhalen/oa/actions/runs/38491424380">38491424380</a>        |
| Ref          | <code>refs/heads/main</code>                                                               |
| Event commit | <code>fe917988b3611965f7158f3eb4540fa9ac394076</code> (in the history of the built commit) |

## Tools

|          |         |
|----------|---------|
| epythet  | 0.2.17  |
| Sphinx   | 9.1.0   |
| docutils | 0.22.4  |
| Python   | 3.12.15 |

## Configuration as resolved

|               |                                                                   |
|---------------|-------------------------------------------------------------------|
| theme         | <code>auto</code> (Sphinx theme <code>sphinxawesome_theme</code>) |
| accent        | <code>#006c72</code>                                              |
| api_generator | <code>autosummary</code>                                          |
| ignore        | <code>tests/</code>, <code>scrap/</code>, <code>examples/</code>  |
| agent_outputs | <code>true</code>                                                 |
| aggregates    | <code>md</code>                                                   |
| ai_artifacts  | <code>true</code>                                                 |

## Package on PyPI

Latest release: <a href="https://pypi.org/project/oa/0.1.60/">0.1.60</a>, the same as the documented version.

## Reproduce

```bash
git clone https://github.com/thorwhalen/oa && cd oa
git checkout 617693d165626d37fa9fba8df44e332d2758d202
pip install "epythet==0.2.17"
epythet quickstart . --ignore tests/ scrap/ examples/
```

The same data, for machines: <a href="build_info.json"><code>build_info.json</code></a> (schema version 1).


# api.html.md

# API reference

| [`oa`](_autosummary/oa.html.md#module-oa)   | Python facade to OpenAi functionality.   |
|-----------------------------------------------------------------|------------------------------------------|


