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
