API reference

The okcourse package provides a lightweight interface for Python applications to use AI models to generate audiobook-style courses containing lectures on any topic.

Given a course title, a course generator like the OpenAIAsyncCourseGenerator will fetch the following from an AI service provider's API:

Course outline
Lecture text for the topics in the outline
Cover image for the audio file album art
Audio file from the lecture text

Modules:

Name	Description
`constants`	Values that define constraints related to course content or its generation by course `generators`.
`generators`	The `generators` package includes course generators compatible with AI service provider APIs.
`models`	Pydantic models representing a course and its generation settings, outline, and lectures.
`prompt_library`	A collection of prompt sets for different types of courses.
`utils`	Utility functions for the `okcourse` package.

Classes:

Name	Description
`Course`	A `Course` is the container for its content and the settings a course generator uses to generate that content.
`CourseGenerationInfo`	Details about the course generation, including okcourse version, token counts (input and output), and durations.
`CourseGenerator`	Abstract base class for generating a course outline, its lectures, a cover image, and audio for the course.
`CourseLecture`	A lecture in a course, including its title text content.
`CourseLectureTopic`	A topic covered by a lecture in a course.
`CourseOutline`	The outline of a course, including its title and the topics covered by each lecture.
`CoursePromptSet`	Bundles a set of prompts used for generating a certain type of course, like academic, storytelling, or technical.
`CourseSettings`	Runtime-modifiable settings that configure the behavior of a course `generator`.
`OpenAIAsyncGenerator`	Uses the OpenAI API to generate course content asynchronously.

Course `pydantic-model`

A Course is the container for its content and the settings a course generator uses to generate that content.

Create a Course instance, modify its settings, and then pass the Course to a course generator like OpenAIAsyncGenerator. You can then start generating content with the generator's methods like generate_outline().

Show JSON schema:

{
  "$defs": {
    "CourseGenerationInfo": {
      "description": "Details about the course generation, including okcourse version, token counts (input and output), and durations.\n\nYou can estimate the cost of course generation based on the token count values in this class and the models that\nwere used to produce them. The model names are specified in the [`CourseSettings`][okcourse.CourseSettings] and most\nAI service providers make cost-per-token pricing available on their website, which may vary by provider and your\naccount or subscription level.",
      "properties": {
        "okcourse_version": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The version of the okcourse library used to generate the course.",
          "title": "Okcourse Version"
        },
        "generator_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The type of course generator used to generate the course content.",
          "title": "Generator Type"
        },
        "lecture_input_token_count": {
          "default": 0,
          "description": "The total number of tokens sent to the text completion endpoint when requesting the lecture content for the course. This count does NOT include the tokens sent when requesting the outline.",
          "title": "Lecture Input Token Count",
          "type": "integer"
        },
        "lecture_output_token_count": {
          "default": 0,
          "description": "The total number of tokens returned by the text completion endpoint is response to lecture generation request for the course. This count does NOT include the tokens returned for outline requests.",
          "title": "Lecture Output Token Count",
          "type": "integer"
        },
        "outline_input_token_count": {
          "default": 0,
          "description": "The total number of tokens sent to the text completion endpoint when requesting the outline(s) for the course. This count does NOT include the tokens sent when requesting the course's lecture content.",
          "title": "Outline Input Token Count",
          "type": "integer"
        },
        "outline_output_token_count": {
          "default": 0,
          "description": "The total number of tokens returned by the text completion endpoint is response to outline generation requests for the course. This count does NOT include the tokens returned for lecture requests.",
          "title": "Outline Output Token Count",
          "type": "integer"
        },
        "tts_character_count": {
          "default": 0,
          "description": "The total number of characters sent to the TTS endpoint.",
          "title": "Tts Character Count",
          "type": "integer"
        },
        "outline_gen_elapsed_seconds": {
          "default": 0.0,
          "description": "The time in seconds spent generating the course outline. This value is not cumulative and contains only the most recent outline generation time.",
          "title": "Outline Gen Elapsed Seconds",
          "type": "number"
        },
        "lecture_gen_elapsed_seconds": {
          "default": 0.0,
          "description": "The time in seconds spent generating the course lectures. This value is not cumulative and contains only the most recent lecture generation time.",
          "title": "Lecture Gen Elapsed Seconds",
          "type": "number"
        },
        "image_gen_elapsed_seconds": {
          "default": 0.0,
          "description": "The time in seconds spent generating the course cover image. This value is not cumulative and contains only the most recent image generation time.",
          "title": "Image Gen Elapsed Seconds",
          "type": "number"
        },
        "audio_gen_elapsed_seconds": {
          "default": 0.0,
          "description": "The time in seconds spent generating and processing the course audio file. This value is not cumulative and contains only the most recent audio generation time. Processing includes combining the speech audio chunks into a single file and saving it to disk.",
          "title": "Audio Gen Elapsed Seconds",
          "type": "number"
        },
        "num_images_generated": {
          "default": 0,
          "description": "The number of images generated for the course.",
          "title": "Num Images Generated",
          "type": "integer"
        },
        "audio_file_path": {
          "anyOf": [
            {
              "format": "path",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The path to the audio file generated from the course content.",
          "title": "Audio File Path"
        },
        "image_file_path": {
          "anyOf": [
            {
              "format": "path",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The path to the cover image generated for the course.",
          "title": "Image File Path"
        }
      },
      "title": "CourseGenerationInfo",
      "type": "object"
    },
    "CourseLecture": {
      "description": "A lecture in a [course][okcourse.models.Course], including its title text content.",
      "properties": {
        "number": {
          "description": "The position number of the lecture within the series.",
          "title": "Number",
          "type": "integer"
        },
        "title": {
          "description": "The topic of a lecture within a course.",
          "title": "Title",
          "type": "string"
        },
        "subtopics": {
          "description": "The subtopics covered in the lecture.",
          "items": {
            "type": "string"
          },
          "title": "Subtopics",
          "type": "array"
        },
        "text": {
          "description": "The unabridged text content of the lecture.",
          "title": "Text",
          "type": "string"
        }
      },
      "required": [
        "number",
        "title",
        "subtopics",
        "text"
      ],
      "title": "CourseLecture",
      "type": "object"
    },
    "CourseLectureTopic": {
      "description": "A topic covered by a [lecture][okcourse.models.CourseLecture] in a course.",
      "properties": {
        "number": {
          "description": "The position number of the lecture within the series.",
          "title": "Number",
          "type": "integer"
        },
        "title": {
          "description": "The topic of a lecture within a course.",
          "title": "Title",
          "type": "string"
        },
        "subtopics": {
          "description": "The subtopics covered in the lecture.",
          "items": {
            "type": "string"
          },
          "title": "Subtopics",
          "type": "array"
        }
      },
      "required": [
        "number",
        "title",
        "subtopics"
      ],
      "title": "CourseLectureTopic",
      "type": "object"
    },
    "CourseOutline": {
      "description": "The outline of a course, including its title and the topics covered by each [lecture][okcourse.models.CourseLecture].",
      "properties": {
        "title": {
          "description": "The title of the course.",
          "title": "Title",
          "type": "string"
        },
        "topics": {
          "description": "The topics covered by each lecture in the series.",
          "items": {
            "$ref": "#/$defs/CourseLectureTopic"
          },
          "title": "Topics",
          "type": "array"
        }
      },
      "required": [
        "title",
        "topics"
      ],
      "title": "CourseOutline",
      "type": "object"
    },
    "CoursePromptSet": {
      "description": "Bundles a set of prompts used for generating a certain type of course, like academic, storytelling, or technical.",
      "properties": {
        "description": {
          "default": "`system` and `user` prompts appropriate for a certain type of course.",
          "description": "A name or description for the type of course this collection of prompts is intended to create.",
          "title": "Description",
          "type": "string"
        },
        "system": {
          "default": null,
          "description": "The `system` prompt guides the language model's style and tone when generating the course outline and lecture text. This prompt should be appropriate for passing to the AI service provider's API along with any of the other prompts (the outline, lecture, or image prompts)",
          "title": "System",
          "type": "string"
        },
        "outline": {
          "default": null,
          "description": "The `user` prompt that contains the course outline generation instructions for the language model. This prompt is passed along with the `system` prompt when requesting an outline.",
          "title": "Outline",
          "type": "string"
        },
        "lecture": {
          "default": null,
          "description": "The `user` prompt that contains the lecture content generation instructions for the language model. This prompt is passed along with the `system` prompt when requesting one of the lectures in the course.",
          "title": "Lecture",
          "type": "string"
        },
        "image": {
          "default": null,
          "description": "The `user` prompt that guides the image model's generation of course cover art. This prompt is passed along with the `system` prompt when requesting a cover image for the course.",
          "title": "Image",
          "type": "string"
        }
      },
      "title": "CoursePromptSet",
      "type": "object"
    },
    "CourseSettings": {
      "description": "Runtime-modifiable settings that configure the behavior of a course [`generator`][okcourse.generators].\n\nCreate a `Course` instance and then modify its [`Course.settings`][okcourse.models.Course.settings] attribute, which\nis an instance of this class with default values. After configuring the course settings, pass the `Course` instance\nto a course generator's constructor and then to its\n[`generate_outline`][okcourse.generators.CourseGenerator.generate_outline] method to start generating course\ncontent.",
      "properties": {
        "prompts": {
          "$ref": "#/$defs/CoursePromptSet",
          "default": {
            "description": "Academic lecture series",
            "system": "You are an esteemed college professor and expert in your field who typically lectures graduate students. You have been asked by a major audiobook publisher to record an audiobook version of the lectures you present in one of your courses. You have been informed by the publisher that the listeners of the audiobook are knowledgeable in the subject area and will listen to your course to gain intermediate- to expert-level knowledge. Your lecture style is professional, direct, and deeply technical.",
            "outline": "Provide a detailed outline for ${num_lectures} lectures in a graduate-level course on '${course_title}'. List each lecture title numbered. Each lecture should have ${num_subtopics} subtopics listed after the lecture title. Respond only with the outline, omitting any other commentary.",
            "lecture": "Generate the complete unabridged text for a lecture titled '${lecture_title}' in a graduate-level course named '${course_title}'. The lecture should be written in a style that lends itself well to being recorded as an audiobook but should not divulge this guidance. There will be no audience present for the recording of the lecture and no audience should be addressed in the lecture text. Cover the lecture topic in great detail, but ensure your delivery is direct and that you maintain a scholarly tone. Aim for a final product whose textual content flows smoothly when read aloud and can be easily understood without visual aids. Produce clean text that lacks markup, lists, code, or any other formatting that might interfere with text-to-speech processing. Ensure the content is original and does not duplicate content from the other lectures in the series:\n${course_outline}",
            "image": "Create a cover art image for the college lecture series titled '${course_title}'. Fill the entire canvas with an academic art style using muted colors that reflects the course material."
          },
          "description": "The prompts that guide the AI models in course generation."
        },
        "num_lectures": {
          "default": 4,
          "description": "The number of lectures that should generated for for the course.",
          "title": "Num Lectures",
          "type": "integer"
        },
        "num_subtopics": {
          "default": 4,
          "description": "The number of subtopics that should be generated for each lecture.",
          "title": "Num Subtopics",
          "type": "integer"
        },
        "output_directory": {
          "default": "/home/runner/.okcourse",
          "description": "Directory for saving generated course content.",
          "format": "path",
          "title": "Output Directory",
          "type": "string"
        },
        "text_model_outline": {
          "default": "gpt-4o",
          "description": "The ID of the text generation model to use for generating course outlines.",
          "title": "Text Model Outline",
          "type": "string"
        },
        "text_model_lecture": {
          "default": "gpt-4o",
          "description": "The ID of the text generation model to use for generating course lectures.",
          "title": "Text Model Lecture",
          "type": "string"
        },
        "image_model": {
          "default": "dall-e-3",
          "description": "The ID of the image generation model to use.",
          "title": "Image Model",
          "type": "string"
        },
        "tts_model": {
          "default": "tts-1",
          "description": "The ID of the text-to-speech model to use.",
          "title": "Tts Model",
          "type": "string"
        },
        "tts_voice": {
          "default": "alloy",
          "description": "The voice to use for text-to-speech audio generation.",
          "title": "Tts Voice",
          "type": "string"
        },
        "log_level": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": 20,
          "description": "Specifies the [Python logging level](https://docs.python.org/3/library/logging.html#logging-levels) for course and course asset generation operations. Set this attribute to one of the Python standard library's[logging levels](https://docs.python.org/3/library/logging.html#logging-levels): `INFO`, `DEBUG`, `WARNING`, `ERROR`, or `CRITICAL`. To disable logging, set this attribute to `None`.",
          "title": "Log Level"
        },
        "log_to_file": {
          "default": false,
          "description": "If logging is enabled (`log_level` is not `None`), write log messages to a file in the ``output_directory``.",
          "title": "Log To File",
          "type": "boolean"
        }
      },
      "title": "CourseSettings",
      "type": "object"
    }
  },
  "description": "A `Course` is the container for its content and the settings a course generator uses to generate that content.\n\nCreate a `Course` instance, modify its [`settings`][okcourse.models.CourseSettings], and then pass the `Course` to a\ncourse generator like\n[`OpenAIAsyncGenerator`][okcourse.generators.OpenAIAsyncGenerator.generate_outline]. You can then start generating\ncontent with the generator's methods like [`generate_outline()`][okcourse.OpenAIAsyncGenerator.generate_outline].",
  "properties": {
    "title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The topic of the course and its lectures. The course title, along with its [`settings.prompts`][okcourse.models.CourseSettings.prompts], are the most influential in determining the course content.",
      "title": "Title"
    },
    "outline": {
      "anyOf": [
        {
          "$ref": "#/$defs/CourseOutline"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The outline for the course that defines the topics for each lecture."
    },
    "lectures": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/CourseLecture"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The lectures that comprise the complete course.",
      "title": "Lectures"
    },
    "settings": {
      "$ref": "#/$defs/CourseSettings",
      "description": "Course [`generators`][okcourse.generators] use these settings to determine the content of the course as well as the behavior of the generation process. Modify these settings to specify the number of lectures to generate for the course, the AI models to use to generate them, the output directory for the generated content, and more."
    },
    "generation_info": {
      "$ref": "#/$defs/CourseGenerationInfo",
      "description": "Details about the course's content generation process, including the version of `okcourse` used, the token and character counts, and the time elapsed."
    }
  },
  "title": "Course",
  "type": "object"
}

Fields:

title (str | None)
outline (CourseOutline | None)
lectures (list[CourseLecture] | None)
settings (CourseSettings)
generation_info (CourseGenerationInfo)

generation_info `pydantic-field`

generation_info: CourseGenerationInfo

Details about the course's content generation process, including the version of okcourse used, the token and character counts, and the time elapsed.

lectures `pydantic-field`

lectures: list[CourseLecture] | None = None

The lectures that comprise the complete course.

outline `pydantic-field`

outline: CourseOutline | None = None

The outline for the course that defines the topics for each lecture.

settings `pydantic-field`

settings: CourseSettings

Course generators use these settings to determine the content of the course as well as the behavior of the generation process. Modify these settings to specify the number of lectures to generate for the course, the AI models to use to generate them, the output directory for the generated content, and more.

title `pydantic-field`

title: str | None = None

The topic of the course and its lectures. The course title, along with its settings.prompts, are the most influential in determining the course content.

CourseGenerationInfo `pydantic-model`

Details about the course generation, including okcourse version, token counts (input and output), and durations.

You can estimate the cost of course generation based on the token count values in this class and the models that were used to produce them. The model names are specified in the CourseSettings and most AI service providers make cost-per-token pricing available on their website, which may vary by provider and your account or subscription level.

Show JSON schema:

{
  "description": "Details about the course generation, including okcourse version, token counts (input and output), and durations.\n\nYou can estimate the cost of course generation based on the token count values in this class and the models that\nwere used to produce them. The model names are specified in the [`CourseSettings`][okcourse.CourseSettings] and most\nAI service providers make cost-per-token pricing available on their website, which may vary by provider and your\naccount or subscription level.",
  "properties": {
    "okcourse_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The version of the okcourse library used to generate the course.",
      "title": "Okcourse Version"
    },
    "generator_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The type of course generator used to generate the course content.",
      "title": "Generator Type"
    },
    "lecture_input_token_count": {
      "default": 0,
      "description": "The total number of tokens sent to the text completion endpoint when requesting the lecture content for the course. This count does NOT include the tokens sent when requesting the outline.",
      "title": "Lecture Input Token Count",
      "type": "integer"
    },
    "lecture_output_token_count": {
      "default": 0,
      "description": "The total number of tokens returned by the text completion endpoint is response to lecture generation request for the course. This count does NOT include the tokens returned for outline requests.",
      "title": "Lecture Output Token Count",
      "type": "integer"
    },
    "outline_input_token_count": {
      "default": 0,
      "description": "The total number of tokens sent to the text completion endpoint when requesting the outline(s) for the course. This count does NOT include the tokens sent when requesting the course's lecture content.",
      "title": "Outline Input Token Count",
      "type": "integer"
    },
    "outline_output_token_count": {
      "default": 0,
      "description": "The total number of tokens returned by the text completion endpoint is response to outline generation requests for the course. This count does NOT include the tokens returned for lecture requests.",
      "title": "Outline Output Token Count",
      "type": "integer"
    },
    "tts_character_count": {
      "default": 0,
      "description": "The total number of characters sent to the TTS endpoint.",
      "title": "Tts Character Count",
      "type": "integer"
    },
    "outline_gen_elapsed_seconds": {
      "default": 0.0,
      "description": "The time in seconds spent generating the course outline. This value is not cumulative and contains only the most recent outline generation time.",
      "title": "Outline Gen Elapsed Seconds",
      "type": "number"
    },
    "lecture_gen_elapsed_seconds": {
      "default": 0.0,
      "description": "The time in seconds spent generating the course lectures. This value is not cumulative and contains only the most recent lecture generation time.",
      "title": "Lecture Gen Elapsed Seconds",
      "type": "number"
    },
    "image_gen_elapsed_seconds": {
      "default": 0.0,
      "description": "The time in seconds spent generating the course cover image. This value is not cumulative and contains only the most recent image generation time.",
      "title": "Image Gen Elapsed Seconds",
      "type": "number"
    },
    "audio_gen_elapsed_seconds": {
      "default": 0.0,
      "description": "The time in seconds spent generating and processing the course audio file. This value is not cumulative and contains only the most recent audio generation time. Processing includes combining the speech audio chunks into a single file and saving it to disk.",
      "title": "Audio Gen Elapsed Seconds",
      "type": "number"
    },
    "num_images_generated": {
      "default": 0,
      "description": "The number of images generated for the course.",
      "title": "Num Images Generated",
      "type": "integer"
    },
    "audio_file_path": {
      "anyOf": [
        {
          "format": "path",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The path to the audio file generated from the course content.",
      "title": "Audio File Path"
    },
    "image_file_path": {
      "anyOf": [
        {
          "format": "path",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The path to the cover image generated for the course.",
      "title": "Image File Path"
    }
  },
  "title": "CourseGenerationInfo",
  "type": "object"
}

Fields:

audio_file_path `pydantic-field`

audio_file_path: Path | None = None

The path to the audio file generated from the course content.

audio_gen_elapsed_seconds `pydantic-field`

audio_gen_elapsed_seconds: float = 0.0

The time in seconds spent generating and processing the course audio file. This value is not cumulative and contains only the most recent audio generation time. Processing includes combining the speech audio chunks into a single file and saving it to disk.

generator_type `pydantic-field`

generator_type: str | None = None

The type of course generator used to generate the course content.

image_file_path `pydantic-field`

image_file_path: Path | None = None

The path to the cover image generated for the course.

image_gen_elapsed_seconds `pydantic-field`

image_gen_elapsed_seconds: float = 0.0

The time in seconds spent generating the course cover image. This value is not cumulative and contains only the most recent image generation time.

lecture_gen_elapsed_seconds `pydantic-field`

lecture_gen_elapsed_seconds: float = 0.0

The time in seconds spent generating the course lectures. This value is not cumulative and contains only the most recent lecture generation time.

lecture_input_token_count `pydantic-field`

lecture_input_token_count: int = 0

The total number of tokens sent to the text completion endpoint when requesting the lecture content for the course. This count does NOT include the tokens sent when requesting the outline.

lecture_output_token_count `pydantic-field`

lecture_output_token_count: int = 0

The total number of tokens returned by the text completion endpoint is response to lecture generation request for the course. This count does NOT include the tokens returned for outline requests.

num_images_generated `pydantic-field`

num_images_generated: int = 0

The number of images generated for the course.

okcourse_version `pydantic-field`

okcourse_version: str | None = None

The version of the okcourse library used to generate the course.

outline_gen_elapsed_seconds `pydantic-field`

outline_gen_elapsed_seconds: float = 0.0

The time in seconds spent generating the course outline. This value is not cumulative and contains only the most recent outline generation time.

outline_input_token_count `pydantic-field`

outline_input_token_count: int = 0

The total number of tokens sent to the text completion endpoint when requesting the outline(s) for the course. This count does NOT include the tokens sent when requesting the course's lecture content.

outline_output_token_count `pydantic-field`

outline_output_token_count: int = 0

The total number of tokens returned by the text completion endpoint is response to outline generation requests for the course. This count does NOT include the tokens returned for lecture requests.

tts_character_count `pydantic-field`

tts_character_count: int = 0

The total number of characters sent to the TTS endpoint.

CourseGenerator

CourseGenerator(course: Course)

Abstract base class for generating a course outline, its lectures, a cover image, and audio for the course.

Parameters:

Name	Type	Description	Default
`course`	`Course`	The course to generate content for.	required

Attributes:

Name	Type	Description
`log`	`getLogger`	The logger for the generator.

Subclasses must implement the abstract methods to generate the course outline, lectures, image, and audio.

Methods:

Name	Description
`generate_audio`	Uses a text-to-speech (TTS) model to generate audio for the course from its lectures.
`generate_image`	Uses an image generation model to generate a cover image for the course based on its title.
`generate_lectures`	Uses a generative pre-trained transformer (GPT) to generate the lectures in the course outline.
`generate_outline`	Uses a generative pre-trained transformer (GPT) to generate an outline for the course based on its title.

Attributes:

Name	Type	Description
`log`	`getLogger`	The logger for the generator.

log `instance-attribute`

log: getLogger = None

The logger for the generator.

generate_audio `abstractmethod`

generate_audio(course: Course) -> Course

Uses a text-to-speech (TTS) model to generate audio for the course from its lectures.

This method requires that the course has had its lectures generated with a call to generate_lectures before being passed to this method.

Returns:

Name	Type	Description
`Course`	`Course`	The course with the `audio_file_path` attribute set in its `generation_info` attribute.

generate_image `abstractmethod`

generate_image(course: Course) -> Course

Uses an image generation model to generate a cover image for the course based on its title.

Parameters:

Name	Type	Description	Default
`course`	`Course`	The course to generate an image for.	required

Returns:

Name	Type	Description
`Course`	`Course`	The course with the `image_file_path` attribute set in its `generation_info` attribute.

generate_lectures `abstractmethod`

generate_lectures(course: Course) -> Course

Uses a generative pre-trained transformer (GPT) to generate the lectures in the course outline.

This method requires that the course has had its outline generated with a call to generate_outline before being passed to this method.

Parameters:

Name	Type	Description	Default
`course`	`Course`	The course to generate lectures for. The given course must have had its outline generated and its `outline` attribute set.	required

Returns:

Name	Type	Description
`Course`	`Course`	The course with its `lectures` attribute set.

generate_outline `abstractmethod`

generate_outline(course: Course) -> Course

Uses a generative pre-trained transformer (GPT) to generate an outline for the course based on its title.

Modify the Course.settings attribute before calling this method to customize the generation process and its output.

Parameters:

Name	Type	Description	Default
`course`	`Course`	The course to generate an outline for.	required

Returns:

Name	Type	Description
`Course`	`Course`	The course with its `outline` attribute set.

CourseLecture `pydantic-model`

A lecture in a course, including its title text content.

Show JSON schema:

{
  "description": "A lecture in a [course][okcourse.models.Course], including its title text content.",
  "properties": {
    "number": {
      "description": "The position number of the lecture within the series.",
      "title": "Number",
      "type": "integer"
    },
    "title": {
      "description": "The topic of a lecture within a course.",
      "title": "Title",
      "type": "string"
    },
    "subtopics": {
      "description": "The subtopics covered in the lecture.",
      "items": {
        "type": "string"
      },
      "title": "Subtopics",
      "type": "array"
    },
    "text": {
      "description": "The unabridged text content of the lecture.",
      "title": "Text",
      "type": "string"
    }
  },
  "required": [
    "number",
    "title",
    "subtopics",
    "text"
  ],
  "title": "CourseLecture",
  "type": "object"
}

Fields:

text (str)

text `pydantic-field`

text: str

The unabridged text content of the lecture.

CourseLectureTopic `pydantic-model`

A topic covered by a lecture in a course.

Show JSON schema:

{
  "description": "A topic covered by a [lecture][okcourse.models.CourseLecture] in a course.",
  "properties": {
    "number": {
      "description": "The position number of the lecture within the series.",
      "title": "Number",
      "type": "integer"
    },
    "title": {
      "description": "The topic of a lecture within a course.",
      "title": "Title",
      "type": "string"
    },
    "subtopics": {
      "description": "The subtopics covered in the lecture.",
      "items": {
        "type": "string"
      },
      "title": "Subtopics",
      "type": "array"
    }
  },
  "required": [
    "number",
    "title",
    "subtopics"
  ],
  "title": "CourseLectureTopic",
  "type": "object"
}

Fields:

number (int)
title (str)
subtopics (list[str])

number `pydantic-field`

number: int

The position number of the lecture within the series.

subtopics `pydantic-field`

subtopics: list[str]

The subtopics covered in the lecture.

title `pydantic-field`

title: str

The topic of a lecture within a course.

CourseOutline `pydantic-model`

The outline of a course, including its title and the topics covered by each lecture.

Show JSON schema:

{
  "$defs": {
    "CourseLectureTopic": {
      "description": "A topic covered by a [lecture][okcourse.models.CourseLecture] in a course.",
      "properties": {
        "number": {
          "description": "The position number of the lecture within the series.",
          "title": "Number",
          "type": "integer"
        },
        "title": {
          "description": "The topic of a lecture within a course.",
          "title": "Title",
          "type": "string"
        },
        "subtopics": {
          "description": "The subtopics covered in the lecture.",
          "items": {
            "type": "string"
          },
          "title": "Subtopics",
          "type": "array"
        }
      },
      "required": [
        "number",
        "title",
        "subtopics"
      ],
      "title": "CourseLectureTopic",
      "type": "object"
    }
  },
  "description": "The outline of a course, including its title and the topics covered by each [lecture][okcourse.models.CourseLecture].",
  "properties": {
    "title": {
      "description": "The title of the course.",
      "title": "Title",
      "type": "string"
    },
    "topics": {
      "description": "The topics covered by each lecture in the series.",
      "items": {
        "$ref": "#/$defs/CourseLectureTopic"
      },
      "title": "Topics",
      "type": "array"
    }
  },
  "required": [
    "title",
    "topics"
  ],
  "title": "CourseOutline",
  "type": "object"
}

Fields:

title (str)
topics (list[CourseLectureTopic])

title `pydantic-field`

title: str

The title of the course.

topics `pydantic-field`

topics: list[CourseLectureTopic]

The topics covered by each lecture in the series.

CoursePromptSet `pydantic-model`

Bundles a set of prompts used for generating a certain type of course, like academic, storytelling, or technical.

Show JSON schema:

{
  "description": "Bundles a set of prompts used for generating a certain type of course, like academic, storytelling, or technical.",
  "properties": {
    "description": {
      "default": "`system` and `user` prompts appropriate for a certain type of course.",
      "description": "A name or description for the type of course this collection of prompts is intended to create.",
      "title": "Description",
      "type": "string"
    },
    "system": {
      "default": null,
      "description": "The `system` prompt guides the language model's style and tone when generating the course outline and lecture text. This prompt should be appropriate for passing to the AI service provider's API along with any of the other prompts (the outline, lecture, or image prompts)",
      "title": "System",
      "type": "string"
    },
    "outline": {
      "default": null,
      "description": "The `user` prompt that contains the course outline generation instructions for the language model. This prompt is passed along with the `system` prompt when requesting an outline.",
      "title": "Outline",
      "type": "string"
    },
    "lecture": {
      "default": null,
      "description": "The `user` prompt that contains the lecture content generation instructions for the language model. This prompt is passed along with the `system` prompt when requesting one of the lectures in the course.",
      "title": "Lecture",
      "type": "string"
    },
    "image": {
      "default": null,
      "description": "The `user` prompt that guides the image model's generation of course cover art. This prompt is passed along with the `system` prompt when requesting a cover image for the course.",
      "title": "Image",
      "type": "string"
    }
  },
  "title": "CoursePromptSet",
  "type": "object"
}

Fields:

description (str)
system (str)
outline (str)
lecture (str)
image (str)

description `pydantic-field`

description: str = (
    "`system` and `user` prompts appropriate for a certain type of course."
)

A name or description for the type of course this collection of prompts is intended to create.

image `pydantic-field`

image: str = None

The user prompt that guides the image model's generation of course cover art. This prompt is passed along with the system prompt when requesting a cover image for the course.

lecture `pydantic-field`

lecture: str = None

The user prompt that contains the lecture content generation instructions for the language model. This prompt is passed along with the system prompt when requesting one of the lectures in the course.

outline `pydantic-field`

outline: str = None

The user prompt that contains the course outline generation instructions for the language model. This prompt is passed along with the system prompt when requesting an outline.

system `pydantic-field`

system: str = None

The system prompt guides the language model's style and tone when generating the course outline and lecture text. This prompt should be appropriate for passing to the AI service provider's API along with any of the other prompts (the outline, lecture, or image prompts)

CourseSettings `pydantic-model`

Runtime-modifiable settings that configure the behavior of a course generator.

Create a Course instance and then modify its Course.settings attribute, which is an instance of this class with default values. After configuring the course settings, pass the Course instance to a course generator's constructor and then to its generate_outline method to start generating course content.

Show JSON schema:

{
  "$defs": {
    "CoursePromptSet": {
      "description": "Bundles a set of prompts used for generating a certain type of course, like academic, storytelling, or technical.",
      "properties": {
        "description": {
          "default": "`system` and `user` prompts appropriate for a certain type of course.",
          "description": "A name or description for the type of course this collection of prompts is intended to create.",
          "title": "Description",
          "type": "string"
        },
        "system": {
          "default": null,
          "description": "The `system` prompt guides the language model's style and tone when generating the course outline and lecture text. This prompt should be appropriate for passing to the AI service provider's API along with any of the other prompts (the outline, lecture, or image prompts)",
          "title": "System",
          "type": "string"
        },
        "outline": {
          "default": null,
          "description": "The `user` prompt that contains the course outline generation instructions for the language model. This prompt is passed along with the `system` prompt when requesting an outline.",
          "title": "Outline",
          "type": "string"
        },
        "lecture": {
          "default": null,
          "description": "The `user` prompt that contains the lecture content generation instructions for the language model. This prompt is passed along with the `system` prompt when requesting one of the lectures in the course.",
          "title": "Lecture",
          "type": "string"
        },
        "image": {
          "default": null,
          "description": "The `user` prompt that guides the image model's generation of course cover art. This prompt is passed along with the `system` prompt when requesting a cover image for the course.",
          "title": "Image",
          "type": "string"
        }
      },
      "title": "CoursePromptSet",
      "type": "object"
    }
  },
  "description": "Runtime-modifiable settings that configure the behavior of a course [`generator`][okcourse.generators].\n\nCreate a `Course` instance and then modify its [`Course.settings`][okcourse.models.Course.settings] attribute, which\nis an instance of this class with default values. After configuring the course settings, pass the `Course` instance\nto a course generator's constructor and then to its\n[`generate_outline`][okcourse.generators.CourseGenerator.generate_outline] method to start generating course\ncontent.",
  "properties": {
    "prompts": {
      "$ref": "#/$defs/CoursePromptSet",
      "default": {
        "description": "Academic lecture series",
        "system": "You are an esteemed college professor and expert in your field who typically lectures graduate students. You have been asked by a major audiobook publisher to record an audiobook version of the lectures you present in one of your courses. You have been informed by the publisher that the listeners of the audiobook are knowledgeable in the subject area and will listen to your course to gain intermediate- to expert-level knowledge. Your lecture style is professional, direct, and deeply technical.",
        "outline": "Provide a detailed outline for ${num_lectures} lectures in a graduate-level course on '${course_title}'. List each lecture title numbered. Each lecture should have ${num_subtopics} subtopics listed after the lecture title. Respond only with the outline, omitting any other commentary.",
        "lecture": "Generate the complete unabridged text for a lecture titled '${lecture_title}' in a graduate-level course named '${course_title}'. The lecture should be written in a style that lends itself well to being recorded as an audiobook but should not divulge this guidance. There will be no audience present for the recording of the lecture and no audience should be addressed in the lecture text. Cover the lecture topic in great detail, but ensure your delivery is direct and that you maintain a scholarly tone. Aim for a final product whose textual content flows smoothly when read aloud and can be easily understood without visual aids. Produce clean text that lacks markup, lists, code, or any other formatting that might interfere with text-to-speech processing. Ensure the content is original and does not duplicate content from the other lectures in the series:\n${course_outline}",
        "image": "Create a cover art image for the college lecture series titled '${course_title}'. Fill the entire canvas with an academic art style using muted colors that reflects the course material."
      },
      "description": "The prompts that guide the AI models in course generation."
    },
    "num_lectures": {
      "default": 4,
      "description": "The number of lectures that should generated for for the course.",
      "title": "Num Lectures",
      "type": "integer"
    },
    "num_subtopics": {
      "default": 4,
      "description": "The number of subtopics that should be generated for each lecture.",
      "title": "Num Subtopics",
      "type": "integer"
    },
    "output_directory": {
      "default": "/home/runner/.okcourse",
      "description": "Directory for saving generated course content.",
      "format": "path",
      "title": "Output Directory",
      "type": "string"
    },
    "text_model_outline": {
      "default": "gpt-4o",
      "description": "The ID of the text generation model to use for generating course outlines.",
      "title": "Text Model Outline",
      "type": "string"
    },
    "text_model_lecture": {
      "default": "gpt-4o",
      "description": "The ID of the text generation model to use for generating course lectures.",
      "title": "Text Model Lecture",
      "type": "string"
    },
    "image_model": {
      "default": "dall-e-3",
      "description": "The ID of the image generation model to use.",
      "title": "Image Model",
      "type": "string"
    },
    "tts_model": {
      "default": "tts-1",
      "description": "The ID of the text-to-speech model to use.",
      "title": "Tts Model",
      "type": "string"
    },
    "tts_voice": {
      "default": "alloy",
      "description": "The voice to use for text-to-speech audio generation.",
      "title": "Tts Voice",
      "type": "string"
    },
    "log_level": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": 20,
      "description": "Specifies the [Python logging level](https://docs.python.org/3/library/logging.html#logging-levels) for course and course asset generation operations. Set this attribute to one of the Python standard library's[logging levels](https://docs.python.org/3/library/logging.html#logging-levels): `INFO`, `DEBUG`, `WARNING`, `ERROR`, or `CRITICAL`. To disable logging, set this attribute to `None`.",
      "title": "Log Level"
    },
    "log_to_file": {
      "default": false,
      "description": "If logging is enabled (`log_level` is not `None`), write log messages to a file in the ``output_directory``.",
      "title": "Log To File",
      "type": "boolean"
    }
  },
  "title": "CourseSettings",
  "type": "object"
}

Fields:

image_model `pydantic-field`

image_model: str = 'dall-e-3'

The ID of the image generation model to use.

log_level `pydantic-field`

log_level: int | None = INFO

Specifies the Python logging level for course and course asset generation operations. Set this attribute to one of the Python standard library'slogging levels: INFO, DEBUG, WARNING, ERROR, or CRITICAL. To disable logging, set this attribute to None.

log_to_file `pydantic-field`

log_to_file: bool = False

If logging is enabled (log_level is not None), write log messages to a file in the output_directory.

num_lectures `pydantic-field`

num_lectures: int = 4

The number of lectures that should generated for for the course.

num_subtopics `pydantic-field`

num_subtopics: int = 4

The number of subtopics that should be generated for each lecture.

output_directory `pydantic-field`

output_directory: Path = expanduser()

Directory for saving generated course content.

prompts `pydantic-field`

prompts: CoursePromptSet = _DEFAULT_PROMPT_SET

The prompts that guide the AI models in course generation.

text_model_lecture `pydantic-field`

text_model_lecture: str = 'gpt-4o'

The ID of the text generation model to use for generating course lectures.

text_model_outline `pydantic-field`

text_model_outline: str = 'gpt-4o'

The ID of the text generation model to use for generating course outlines.

tts_model `pydantic-field`

tts_model: str = 'tts-1'

The ID of the text-to-speech model to use.

tts_voice `pydantic-field`

tts_voice: str = 'alloy'

The voice to use for text-to-speech audio generation.

OpenAIAsyncGenerator

OpenAIAsyncGenerator(course: Course)

Uses the OpenAI API to generate course content asynchronously.

Use the OpenAIAsyncGenerator to generate a course outline, lectures, cover image, and audio file for a course.

Examples: Generate a full course, including its outline, lectures, cover image, and audio file:

import asyncio
from okcourse import Course, OpenAIAsyncGenerator


async def main() -> None:
    """Use the OpenAIAsyncGenerator to generate a complete course."""

    # Create a course, configure its settings, and initialize the generator
    course = Course(title="From AGI to ASI: Paperclips, Gray Goo, and You")
    generator = OpenAIAsyncGenerator(course)

    # Generate all course content with - these call AI provider APIs
    course = await generator.generate_outline(course)
    course = await generator.generate_lectures(course)
    course = await generator.generate_image(course)
    course = await generator.generate_audio(course)

    # A Course is a Pydantic model, as are its nested models
    print(course.model_dump_json(indent=2))


if __name__ == "__main__":
    asyncio.run(main())

Parameters:

Name	Type	Description	Default
`course`	`Course`	The course to generate content for.	required

Methods:

Name	Description
`generate_audio`	Generates an audio file from the combined text of the lectures in the given course using a TTS AI model.
`generate_course`	Generates a complete course, including its outline, lectures, a cover image, and audio.
`generate_image`	Generates cover art for the course with the given outline.
`generate_lectures`	Generates the text for the lectures in the course outline in the settings.
`generate_outline`	Generates a course outline based on its `title` and other `settings`.

Attributes:

Name	Type	Description
`client`

client `instance-attribute`

client = AsyncOpenAI()

generate_audio `async`

generate_audio(course: Course) -> Course

Generates an audio file from the combined text of the lectures in the given course using a TTS AI model.

Returns:

Type	Description
`Course`	The course with its `audio_file_path` attribute set which points to the TTS-generated file.

generate_course `async`

generate_course(course: Course) -> Course

Generates a complete course, including its outline, lectures, a cover image, and audio.

Parameters:

Name	Type	Description	Default
`course`	`Course`	The course to generate.	required

Returns:

Name	Type	Description
`Course`	`Course`	The course with all attributes populated by the generation process.

generate_image `async`

generate_image(course: Course) -> Course

Generates cover art for the course with the given outline.

The image is appropriate for use as cover art for the course text or audio.

Returns:

Type	Description
`Course`	The results of the generation process with the `image_bytes` attribute set.

Raises:

Type	Description
`OpenAIError`	If an error occurs during image generation.

generate_lectures `async`

generate_lectures(course: Course) -> Course

Generates the text for the lectures in the course outline in the settings.

To generate an audio file for the Course generated by this method, call generate_audio.

Returns:

Type	Description
`Course`	The Course with its `course.lectures` attribute set.

generate_outline `async`

generate_outline(course: Course) -> Course

Generates a course outline based on its title and other settings.

Set the course's title attribute before calling this method.

Returns:

Name	Type	Description
`Course`	`Course`	The result of the generation process with its `course.outline` attribute set.

Raises:

Type	Description
`ValueError`	If the course has no title.

Examples:

    course = Course(title="From AGI to ASI: Paperclips, Gray Goo, and You")
    generator = OpenAIAsyncGenerator(course)
    course = await generator.generate_outline(course)

API reference

Course pydantic-model

generation_info pydantic-field

lectures pydantic-field

outline pydantic-field

settings pydantic-field

title pydantic-field

CourseGenerationInfo pydantic-model

audio_file_path pydantic-field

audio_gen_elapsed_seconds pydantic-field

generator_type pydantic-field

image_file_path pydantic-field

image_gen_elapsed_seconds pydantic-field

lecture_gen_elapsed_seconds pydantic-field

lecture_input_token_count pydantic-field

lecture_output_token_count pydantic-field

num_images_generated pydantic-field

okcourse_version pydantic-field

outline_gen_elapsed_seconds pydantic-field

outline_input_token_count pydantic-field

outline_output_token_count pydantic-field

tts_character_count pydantic-field

CourseGenerator

log instance-attribute

generate_audio abstractmethod

generate_image abstractmethod

generate_lectures abstractmethod

generate_outline abstractmethod

CourseLecture pydantic-model

text pydantic-field

CourseLectureTopic pydantic-model

number pydantic-field

subtopics pydantic-field

title pydantic-field

CourseOutline pydantic-model

title pydantic-field

topics pydantic-field

CoursePromptSet pydantic-model

description pydantic-field

image pydantic-field

lecture pydantic-field

outline pydantic-field

system pydantic-field

CourseSettings pydantic-model

image_model pydantic-field

log_level pydantic-field

log_to_file pydantic-field

num_lectures pydantic-field

num_subtopics pydantic-field

output_directory pydantic-field

prompts pydantic-field

text_model_lecture pydantic-field

text_model_outline pydantic-field

tts_model pydantic-field

tts_voice pydantic-field

OpenAIAsyncGenerator

client instance-attribute

generate_audio async

generate_course async

generate_image async

generate_lectures async

generate_outline async

Course `pydantic-model`

generation_info `pydantic-field`

lectures `pydantic-field`

outline `pydantic-field`

settings `pydantic-field`

title `pydantic-field`

CourseGenerationInfo `pydantic-model`

audio_file_path `pydantic-field`

audio_gen_elapsed_seconds `pydantic-field`

generator_type `pydantic-field`

image_file_path `pydantic-field`

image_gen_elapsed_seconds `pydantic-field`

lecture_gen_elapsed_seconds `pydantic-field`

lecture_input_token_count `pydantic-field`

lecture_output_token_count `pydantic-field`

num_images_generated `pydantic-field`

okcourse_version `pydantic-field`

outline_gen_elapsed_seconds `pydantic-field`

outline_input_token_count `pydantic-field`

outline_output_token_count `pydantic-field`

tts_character_count `pydantic-field`

log `instance-attribute`

generate_audio `abstractmethod`

generate_image `abstractmethod`

generate_lectures `abstractmethod`

generate_outline `abstractmethod`

CourseLecture `pydantic-model`

text `pydantic-field`

CourseLectureTopic `pydantic-model`

number `pydantic-field`

subtopics `pydantic-field`

title `pydantic-field`

CourseOutline `pydantic-model`

title `pydantic-field`

topics `pydantic-field`

CoursePromptSet `pydantic-model`

description `pydantic-field`

image `pydantic-field`

lecture `pydantic-field`

outline `pydantic-field`

system `pydantic-field`

CourseSettings `pydantic-model`

image_model `pydantic-field`

log_level `pydantic-field`

log_to_file `pydantic-field`

num_lectures `pydantic-field`

num_subtopics `pydantic-field`

output_directory `pydantic-field`

prompts `pydantic-field`

text_model_lecture `pydantic-field`

text_model_outline `pydantic-field`

tts_model `pydantic-field`

tts_voice `pydantic-field`

client `instance-attribute`

generate_audio `async`

generate_course `async`

generate_image `async`

generate_lectures `async`

generate_outline `async`