Skip to main content

​
Function Signature

async def create_conversation[
    TMessage: IMessage
](
    dbname: str | None,
    message_type: type[TMessage],
    name: str = "",
    tags: list[str] | None = None,
    settings: ConversationSettings | None = None,
    extras: dict[str, str] | None = None,
) -> ConversationBase[TMessage]
Create a conversation with the given message type and settings. This is the primary entry point for creating conversations in TypeAgent.

​
Import

from typeagent import create_conversation

​
Parameters

​
dbname
str | None
required
Database name for storage. Pass None for in-memory storage that doesn’t persist when the process exits, or a file path (e.g., "chat.db") for persistent SQLite storage.Example: "my_conversation.db" or None
​
message_type
type[TMessage]
required
The type of messages this conversation will contain. Typically ConversationMessage or TranscriptMessage.Example: ConversationMessage
​
name
str
default:""
Optional name for the conversation, used in diagnostics and metadata.Example: "customer_support_chat"
​
tags
list[str] | None
default:"None"
Optional list of tags for the entire conversation. These are different from per-message tags and apply to the conversation metadata.Example: ["support", "product_feedback"]
​
settings
ConversationSettings | None
default:"None"
Optional conversation settings that control knowledge extraction and indexing behavior. If None, creates default settings with knowledge extraction enabled.See ConversationSettings for configuration options.
​
extras
dict[str, str] | None
default:"None"
Optional dictionary of custom metadata key-value pairs to attach to the conversation.Example: {"user_id": "12345", "session_id": "abc"}

​
Returns

​
conversation
ConversationBase[TMessage]
A fully initialized conversation ready to accept messages. The conversation includes:
  • Message and semantic reference collections
  • All 6 index types (semantic refs, properties, timestamps, message text, related terms, threads)
  • Configured knowledge extraction pipeline

​
Behavior

​
Default Knowledge Extraction

When settings is None, the factory automatically creates settings with knowledge extraction enabled by default: 
settings = ConversationSettings()
settings.semantic_ref_index_settings.auto_extract_knowledge = True

​
Storage Provider Initialization

The function automatically creates the appropriate storage provider:
  • SQLite when dbname is a file path
  • In-memory when dbname is None

​
Index Creation

All 6 secondary indexes are created and initialized:
  1. Semantic reference index - term to knowledge mappings
  2. Property index - fast name/value property lookups
  3. Timestamp index - date range queries
  4. Message text index - semantic search over message content
  5. Related terms index - term synonyms and fuzzy matching
  6. Conversation threads - thread descriptions and groupings

​
Examples

​
Basic In-Memory Conversation

from typeagent import create_conversation
from typeagent.knowpro.universal_message import ConversationMessage

conv = await create_conversation(
    dbname=None,  # In-memory storage
    message_type=ConversationMessage,
    name="quick_chat"
)

​
Persistent Conversation with Custom Settings

from typeagent import create_conversation
from typeagent.knowpro.universal_message import ConversationMessage
from typeagent.knowpro.convsettings import ConversationSettings
from typeagent.aitools.model_adapters import create_embedding_model

# Create custom embedding model
embedding_model = create_embedding_model("openai:text-embedding-3-small")

# Configure settings
settings = ConversationSettings(model=embedding_model)
settings.semantic_ref_index_settings.batch_size = 8

conv = await create_conversation(
    dbname="conversations/support.db",
    message_type=ConversationMessage,
    name="customer_support",
    tags=["support", "2024-q1"],
    settings=settings,
    extras={"department": "sales", "region": "us-west"}
)

​
Transcript Processing

from typeagent import create_conversation
from typeagent.transcripts.transcript import TranscriptMessage

conv = await create_conversation(
    dbname="transcripts/meeting_2024_03_06.db",
    message_type=TranscriptMessage,
    name="weekly_standup",
    tags=["team_meeting", "standup"]
)

​
Error Handling

try:
    conv = await create_conversation(
        dbname="existing.db",
        message_type=ConversationMessage
    )
except ValueError as e:
    # Raised if embedding model mismatch with existing DB
    print(f"Configuration error: {e}")
except Exception as e:
    # Database errors, permission issues, etc.
    print(f"Failed to create conversation: {e}")

Build docs developers (and LLMs) love

Get started for freeTalk to us