Documentation Index
Fetch the complete documentation index at: https://mintlify.com/microsoft/typeagent-py/llms.txt
Use this file to discover all available pages before exploring further.
TypeAgent provides powerful querying capabilities using natural language questions and semantic search over your conversation data.
Basic Querying
The simplest way to query a conversation is using the query() method:
from typeagent import create_conversation
from typeagent.transcripts.transcript import TranscriptMessage
# Load existing conversation
conversation = await create_conversation(
"demo.db",
TranscriptMessage
)
# Ask a natural language question
question = "Who volunteered to do the python library?"
answer = await conversation.query(question)
print(answer)
- Query Translation: Convert natural language to search query
- Query Compilation: Compile to executable search expressions
- Search Execution: Find relevant messages and knowledge
- Answer Generation: Synthesize an answer from results
Interactive Query Sessions
For interactive exploration, use a REPL loop:
import asyncio
from dotenv import load_dotenv
from typeagent import create_conversation
from typeagent.transcripts.transcript import TranscriptMessage
load_dotenv()
async def main():
conversation = await create_conversation("demo.db", TranscriptMessage)
print("TypeAgent Query UI (type 'q' to exit)")
while True:
try:
question = input("typeagent> ")
if not question.strip():
continue
if question.strip().lower() in ("quit", "exit", "q"):
break
answer = await conversation.query(question)
print(answer)
print()
except EOFError:
break
except KeyboardInterrupt:
print("\nExiting...")
break
if __name__ == "__main__":
asyncio.run(main())
Query Patterns
TypeAgent supports various query patterns:
Entity Queries
Find information about specific people, organizations, or things:
# Who questions
answer = await conversation.query("Who is Adrian Tchaikovsky?")
answer = await conversation.query("Who sent emails about the meeting?")
# What questions about entities
answer = await conversation.query("What companies were mentioned?")
answer = await conversation.query("What email addresses were used?")
Action Queries
Find events, activities, or communications:
# Action-based questions
answer = await conversation.query("What did Kevin say to Adrian about science fiction?")
answer = await conversation.query("Who volunteered to help with the project?")
answer = await conversation.query("What emails were sent last week?")
Topic Queries
Search by subject or theme:
# Topic-based questions
answer = await conversation.query("What was discussed about AI ethics?")
answer = await conversation.query("How was Asimov mentioned?")
answer = await conversation.query("What are the main points about deployment?")
Temporal Queries
Filter by time periods:
# Time-based questions
answer = await conversation.query("What happened in January 2024?")
answer = await conversation.query("What emails were sent this morning?")
answer = await conversation.query("What was discussed during the first 10 minutes?")
Search Strategies
Semantic Search
Keyword Search
Hybrid Search
Semantic search uses embeddings to find conceptually similar content:# This will find messages about Python even if they don't use the word "Python"
answer = await conversation.query(
"What programming language was discussed?"
)
- Synonyms (“Python” vs “programming language”)
- Related concepts (“async/await” relates to “asynchronous programming”)
- Paraphrases
For exact term matching, use quoted phrases:# Find exact mentions of "async/await"
answer = await conversation.query(
'What was said about "async/await"?'
)
Combine semantic and keyword approaches:# Semantic understanding + specific terms
answer = await conversation.query(
'Explain the discussion about "TypeChat" and its benefits'
)
# Interactive mode
python tools/query.py --database demo.db
# Single query mode
python tools/query.py --database demo.db \
--query "What was discussed about Python?"
# With verbose output
python tools/query.py --database demo.db \
--query "Who spoke about AI?" \
--verbose
# Show statistics
typeagent> @stats
# View conversation history
typeagent> @history
# Clear history
typeagent> @history --clear
# Set history size
typeagent> @history --size 10
# Show debug levels
typeagent> @debug
# Set debug mode
typeagent> @debug debug4=full
# Get help
typeagent> @help
Conversation History
Conversation history enables follow-up questions with pronouns like “it”, “he”, “she”, or “the first point”.
from typeagent.knowpro.convsettings import ConversationSettings
# Configure history size (default: 5)
settings = ConversationSettings()
# History is managed internally when using the query tool
# Example conversation flow:
# User: "Who is Adrian Tchaikovsky?"
# TypeAgent: "Adrian Tchaikovsky is Kevin's favorite science fiction author..."
# Follow-up question works because of history:
# User: "What books did he write?"
# TypeAgent knows "he" refers to Adrian Tchaikovsky
Advanced Query Options
Customizing Search Behavior
You can configure search options when using the lower-level APIs:
from typeagent.knowpro import searchlang
lang_search_options = searchlang.LanguageSearchOptions(
compile_options=searchlang.LanguageQueryCompileOptions(
exact_scope=False, # Allow fuzzy matching
verb_scope=True, # Expand verb synonyms
apply_scope=True # Apply scope filters
),
exact_match=False, # Enable semantic matching
max_message_matches=25 # Limit results
)
# Use in search
result = await searchlang.search_conversation_with_language(
conversation,
query_translator,
"What was discussed?",
lang_search_options
)
Answer Generation Options
Control how answers are synthesized:
from typeagent.knowpro import answers
answer_options = answers.AnswerContextOptions(
entities_top_k=50, # Include top 50 entities
topics_top_k=50, # Include top 50 topics
messages_top_k=None, # Include all relevant messages
chunking=None # No text chunking
)
all_answers, combined = await answers.generate_answers(
answer_translator,
search_results,
conversation,
"What was discussed?",
options=answer_options
)
Result Inspection
Inspect search results programmatically:
from typeagent.knowpro import searchlang
# Perform search
result = await searchlang.search_conversation_with_language(
conversation,
query_translator,
"What was discussed about Python?",
lang_search_options
)
if isinstance(result, typechat.Success):
search_results = result.value
for search_result in search_results:
print(f"Query: {search_result.raw_query_text}")
print(f"Message matches: {len(search_result.message_matches)}")
print(f"Knowledge matches: {len(search_result.knowledge_matches)}")
# Inspect message matches
for match in search_result.message_matches:
msg = await conversation.messages.get_item(match.message_ordinal)
print(f" Score: {match.score}")
print(f" Text: {' '.join(msg.text_chunks)[:100]}...")
Step 1: Check Index Coverage
Ensure your data is properly indexed:
print(f"Messages: {await conversation.messages.size()}")
print(f"Semantic refs: {await conversation.semantic_refs.size()}")
print(f"Semantic ref index: {await conversation.semantic_ref_index.size()}")
if conversation.secondary_indexes:
msg_index = conversation.secondary_indexes.message_index
if msg_index:
print(f"Message index: {await msg_index.size()}")
Step 2: Use Appropriate Embedding Models
Choose the right embedding model for your use case:
from typeagent.knowpro.convsettings import ConversationSettings
from typeagent.aitools.model_adapters import create_embedding_model
# Default: text-embedding-ada-002 (OpenAI)
settings = ConversationSettings()
# Or specify a different model
embedding_model = create_embedding_model("openai:text-embedding-3-small")
settings = ConversationSettings(model=embedding_model)
Track query execution time:
import time
t0 = time.time()
answer = await conversation.query(question)
elapsed = time.time() - t0
print(f"Query completed in {elapsed:.2f}s")
Common Query Patterns
Who/What/Where/When/Why
# Who - entities and people
await conversation.query("Who attended the meeting?")
# What - actions and topics
await conversation.query("What was decided about the project?")
# Where - locations (if available in metadata)
await conversation.query("Where was the conference held?")
# When - temporal queries
await conversation.query("When was the deadline mentioned?")
# Why - reasoning (when discussed in content)
await conversation.query("Why did they choose Python?")
Aggregation Queries
# Summary/overview
await conversation.query("Summarize the main discussion points")
# Lists
await conversation.query("List all the action items mentioned")
# Counts (approximate)
await conversation.query("How many speakers participated?")
Comparison Queries
# Compare entities or topics
await conversation.query("Compare the Python and JavaScript discussions")
# Before/after
await conversation.query("What changed between the first and second meeting?")
Error Handling
Handle query failures gracefully:
import typechat
from typeagent.knowpro import searchlang
result = await searchlang.search_conversation_with_language(
conversation,
query_translator,
question,
lang_search_options
)
if isinstance(result, typechat.Failure):
print(f"Query failed: {result}")
# Handle failure - perhaps retry or ask user to rephrase
else:
search_results = result.value
# Process results
Next Steps
