Application Programming Interface

Conversations Interface

`conversations.Conversation`

Conversations class.

This class is the core of the Conversations package. Use this class to manage your conversation and processing.

Examples:

>>> conversation = Conversation(recording=Path("/path/to/file.m4a"))
>>> conversation.transcribe()
>>> conversation.diarise()
>>> html_report = conversation.report()

`init(recording, num_speakers=0, reload=True, speaker_mapping=None, meeting_datetime=None, attendees=None, transcription=None, transcription_shortened=None, summary=None, summary_automated=None)`

Initialise Conversations class.

Parameters:

Name	Type	Description	Default
`recording`	`Path`	Path to the conversation recording.	required
`num_speakers`	`int`	The number of speakers in the conversation, defaulting to 0 if unknown.	`0`
`reload`	`bool`	If True, try to load an existing saved conversation with the default filename. If False, create a new Conversation instance.	`True`
`speaker_mapping`	`Optional[Dict[str, str]]`	A dictionary mapping speaker IDs to speaker names.	`None`

Returns:

Name	Type	Description
`conversation`	`Conversation`	Instance of Conversation.

`transcribe(method='assembly', model='nano', prompt=" - How are you? - I'm fine, thank you.", language='en')`

Transcribe a conversation using the specified method and model.

Parameters:

Name	Type	Description	Default
`method`	`str`	The transcription method to use, defaults to "assembly". Can be one of whisper or assembly.	`'assembly'`
`model`	`str`	The model to be used for transcription, must be one of tiny, base, small, large, medium, tiny.en, base.en, small.en, medium.en, and openai.en, best, nano. Defaults to "nano".	`'nano'`
`prompt`	`(str, None)`	An optional prompt to be used for transcription, defaults to None.	`" - How are you? - I'm fine, thank you."`
`language`	`str`	The language of the conversation, defaults to "en".	`'en'`

Returns:

Type	Description
`None`

Raises:

Type	Description
`RuntimeError`	If the conversation has already been transcribed.
`ValueError`	If an invalid model name is provided.
`NotImplementedError`	If the method is not supported.

`diarise(method='simple')`

Diarise a conversation.

`shortened_transcript(chunk_num_tokens=128000, shorten_iterations=2)`

Get the shortened transcript of the conversation.

This method returns the previously shortened transcript if available. If not, it computes the shortened transcript first and then returns it.

Parameters:

Name	Type	Description	Default
`chunk_num_tokens`	`int`	The number of tokens to use for each chunk. The default is 7372, which is 90% of the 8k model limit.	`128000`
`shorten_iterations`	`int`	The number of iterations to use when shortening the transcript.	`2`

Returns:

Type	Description
`str`	The shortened transcript of the conversation.

`summarise(force=False, print_summary=True, system_prompt=None, summary_prompt=None, append_prompt=None)`

Generate a summary of the conversation.

Parameters:

Name	Type	Description	Default
`force`	`bool`	If True, generate a new summary even if one already exists.	`False`
`print_summary`	`bool`	If True, print the summary to the console.	`True`
`system_prompt`	`str or None`	The system prompt to use when generating the summary.	`None`
`summary_prompt`	`str or None`	The summary prompt to use when generating the summary.	`None`
`append_prompt`	`str or None`	The append prompt to use when generating the summary.	`None`

Returns:

Name	Type	Description
`summary`	`str`	The generated summary.

`query(query, print_summary=True, system_prompt=None, append_prompt=None)`

Query the conversation.

Parameters:

Name	Type	Description	Default
`query`	`str`	The query to ask the conversation.	required
`print_summary`	`bool`	If True, print the summary to the console.	`True`
`system_prompt`	`str or None`	The system prompt to use when generating the summary.	`None`
`append_prompt`	`str or None`	The append prompt to use when generating the summary.	`None`

Returns:

Name	Type	Description
`summary`	`str`	The generated query response.

`save(file_path=None)`

Save the Conversation object to disk.

Parameters:

Name	Type	Description	Default
`file_path`	`Optional[str]`	The path where the Conversation object will be saved. If None, a default filename based on the audio file path will be used.	`None`

`report(audio_file=None)`

Generate a report of a conversation.

`export_text()`

Export the transcript and diarisation as text.

`conversations.load_conversation(file_path)`

Load a Conversation object from disk.

Parameters:

Name	Type	Description	Default
`file_path`	`str`	The path to the file containing the saved Conversation object.	required

Returns:

Name	Type	Description
`conversation`	`Conversation`	The loaded Conversation object.

Raises:

Type	Description
`ValueError`	If the loaded object is not an instance of the Conversation class.

Low-Level Interface

Transcription

`conversations.transcribe.whisper.process(audio_file, model_name='base.en', prompt=None, language='en')`

Transcribe audio using Whisper.

Parameters:

Name	Type	Description	Default
`audio_file`	`Path`	Path to the audio file.	required
`model_name`	`str`	Name of the whisper model to use. To use the cloud service provided by OpenAI, use "openai.en", by default "base.en".	`'base.en'`
`prompt`	`str`	Prompt to use for the transcription, by default None.	`None`
`language`	`str`	Language to use for the transcription, by default "en".	`'en'`

Returns:

Name	Type	Description
`transcript`	`Dict[str, str]`	Dictionary containing the audio transcript in whisper format.

Diarisation

`conversations.diarise.simple.process(audio_file, num_speakers=2)`

Diarise audio using simple_diarizer.

Parameters:

Name	Type	Description	Default
`audio_file`	`Path`	Path to the audio file.	required
`num_speakers`	`int`	The number of speakers in the conversation.	`2`

Returns:

Name	Type	Description
`segments`	`list[dict]`	List containing the segments as dictionaries.

Report

`conversations.report.generate(transcript, diarisation=None, audio_file=None, speaker_mapping=None)`

Create html page from conversation.

Parameters:

Name	Type	Description	Default
`transcript`	`dict`	Transcript from transcribe module.	required
`diarisation`	`dict`	Speaker diarisation from from diarisation module.	`None`
`audio_file`	`PosixPath \| None`	Path to audio file. If provided, audio will be embedded in the report and timestamps will link to audio times.	`None`
`speaker_mapping`	`dict`	Mapping of old speaker names to new speaker names. For example, {"0": "Alice", "1": "Bob"}.	`None`

Returns:

Name	Type	Description
`report`	`document`	Conversation report as a dominate document.

`conversations.report.export_text(transcript, diarisation=None, speaker_mapping=None, datetimestr=None, attendees=None)`

Create text file from conversation.

Exports the transcript as a text document while grouping segments by speaker (if diarisation is provided) and mapping speaker names (if speaker_mapping is provided).

Parameters:

Name	Type	Description	Default
`transcript`	`Dict[str, Any]`	The transcript data structured as a dictionary with a key "segments" containing a list of dicts. Each dict has a "text" key with the corresponding transcript segment text and optionally a "speaker" key.	required
`diarisation`	`Optional[List[Dict[str, Any]]]`	A list of diarisation data dictionaries. Each dictionary should have the keys "start", "end", and "speaker".	`None`
`speaker_mapping`	`Optional[Dict[str, str]]`	A dictionary that maps speaker identifiers to speaker names. The key is the speaker identifier and the value is the speaker name.	`None`
`datetimestr`	`Optional[str]`	A string representing the date and time of the meeting.	`None`
`attendees`	`Optional[List[str]]`	A list of attendees in the meeting.	`None`

Returns:

Type	Description
`str`	The transcript exported as a text document.

Examples:

>>> transcript = {"segments": [{"text": "Hello, world!", "speaker": "speaker_1"}]}
>>> diarisation = None
>>> speaker_mapping = {"speaker_1": "John"}
>>> export_text(transcript, diarisation, speaker_mapping)
'John: Hello, world!'

Application Programming Interface

Conversations Interface

conversations.Conversation

__init__(recording, num_speakers=0, reload=True, speaker_mapping=None, meeting_datetime=None, attendees=None, transcription=None, transcription_shortened=None, summary=None, summary_automated=None)

transcribe(method='assembly', model='nano', prompt=" - How are you? - I'm fine, thank you.", language='en')

diarise(method='simple')

shortened_transcript(chunk_num_tokens=128000, shorten_iterations=2)

summarise(force=False, print_summary=True, system_prompt=None, summary_prompt=None, append_prompt=None)

query(query, print_summary=True, system_prompt=None, append_prompt=None)

save(file_path=None)

report(audio_file=None)

export_text()

conversations.load_conversation(file_path)

Low-Level Interface

Transcription

conversations.transcribe.whisper.process(audio_file, model_name='base.en', prompt=None, language='en')

Diarisation

conversations.diarise.simple.process(audio_file, num_speakers=2)

Report

conversations.report.generate(transcript, diarisation=None, audio_file=None, speaker_mapping=None)

conversations.report.export_text(transcript, diarisation=None, speaker_mapping=None, datetimestr=None, attendees=None)

`conversations.Conversation`

`init(recording, num_speakers=0, reload=True, speaker_mapping=None, meeting_datetime=None, attendees=None, transcription=None, transcription_shortened=None, summary=None, summary_automated=None)`

`transcribe(method='assembly', model='nano', prompt=" - How are you? - I'm fine, thank you.", language='en')`

`diarise(method='simple')`

`shortened_transcript(chunk_num_tokens=128000, shorten_iterations=2)`

`summarise(force=False, print_summary=True, system_prompt=None, summary_prompt=None, append_prompt=None)`

`query(query, print_summary=True, system_prompt=None, append_prompt=None)`

`save(file_path=None)`

`report(audio_file=None)`

`export_text()`

`conversations.load_conversation(file_path)`

`conversations.transcribe.whisper.process(audio_file, model_name='base.en', prompt=None, language='en')`

`conversations.diarise.simple.process(audio_file, num_speakers=2)`

`conversations.report.generate(transcript, diarisation=None, audio_file=None, speaker_mapping=None)`

`conversations.report.export_text(transcript, diarisation=None, speaker_mapping=None, datetimestr=None, attendees=None)`