Add high-level query() method. Update message index in add_messages_with_indexing

Author: gvanrossum-ms

TADA.md

@@ -4,7 +4,7 @@ Talk at PyBay is on Sat, Oct 18 in SF
 
 ## Software
 
-- Design and implement high-level API to support ingestion and querying
+- Rename utool.py to query.py
 - Unify Podcast and VTT ingestion (use shared message and metadata classes)?
 - Code structure (do podcasts and transcripts need to be under typeagent?)?
 - Distinguish between release deps and build/dev deps?
@@ -33,11 +33,10 @@ Talk at PyBay is on Sat, Oct 18 in SF
 
 - Getting Started
 - Document the high-level API
-- Document the MCP API [NOT YET]
 - Document what should go in `.env` and where it should live
   - And alternatively (first?) what to put in shell env directly
 - Document test/build/release process
-- Document how to run evals (but don't reveal all the data)
+- Document how to run evaluations (but don't reveal all the data)
 
 ## Demos
 

docs/query-method.md

@@ -0,0 +1,99 @@
+# Conversation Query Method
+
+The `query()` method provides a simple, end-to-end API for querying conversations using natural language.
+
+## Usage
+
+```python
+from typeagent import create_conversation
+from typeagent.transcripts.transcript import TranscriptMessage
+
+# Create a conversation
+conv = await create_conversation(
+    "my_conversation.db",
+    TranscriptMessage,
+    name="My Conversation",
+)
+
+# Add messages
+messages: list[TranscriptMessage] = [...]
+await conv.add_messages_with_indexing(messages)
+
+# Query the conversation
+question: str = input("typeagent> ")
+answer: str = await conv.query(question)
+print(answer)
+```
+
+## How It Works
+
+The `query()` method encapsulates the full TypeAgent query pipeline:
+
+1. **Natural Language Understanding**: Uses TypeChat to translate the natural language question into a structured search query
+2. **Search**: Executes the search across the conversation's messages and knowledge base
+3. **Answer Generation**: Uses an LLM to generate a natural language answer based on the search results
+
+## Method Signature
+
+```python
+async def query(self, question: str) -> str:
+    """
+    Run an end-to-end query on the conversation.
+
+    Args:
+        question: The natural language question to answer
+
+    Returns:
+        A natural language answer string. If the answer cannot be determined,
+        returns an explanation of why no answer was found.
+    """
+```
+
+## Behavior
+
+- **Success**: Returns a natural language answer synthesized from the conversation content
+- **No Answer Found**: Returns a message explaining why the answer couldn't be determined
+- **Search Failure**: Returns an error message describing the failure
+
+## Performance Considerations
+
+The `query()` method caches the TypeChat translators per conversation instance, so repeated queries on the same conversation are more efficient.
+
+## Example: Interactive Loop
+
+```python
+while True:
+    question: str = input("typeagent> ")
+    if not question.strip():
+        continue
+    if question.lower() in ("quit", "exit"):
+        break
+    
+    answer: str = await conv.query(question)
+    print(answer)
+```
+
+## Example: Batch Processing
+
+```python
+questions = [
+    "What was discussed?",
+    "Who were the speakers?",
+    "What topics came up?",
+]
+
+for question in questions:
+    answer = await conv.query(question)
+    print(f"Q: {question}")
+    print(f"A: {answer}")
+    print()
+```
+
+## Related APIs
+
+For more control over the query pipeline, you can use the lower-level APIs:
+
+- `searchlang.search_conversation_with_language()` - Search only
+- `answers.generate_answers()` - Answer generation from search results
+
+See `tools/utool.py` for examples of using these lower-level APIs with debugging options.

examples/simple_query_demo.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""
+Simple demo of the conversation.query() method.
+
+This demonstrates the end-to-end query pattern:
+    question = input("typeagent> ")
+    answer = await conv.query(question)
+    print(answer)
+"""
+
+import asyncio
+
+from typeagent import create_conversation
+from typeagent.aitools.embeddings import AsyncEmbeddingModel
+from typeagent.aitools.utils import load_dotenv
+from typeagent.knowpro.convsettings import ConversationSettings
+from typeagent.transcripts.transcript import TranscriptMessage, TranscriptMessageMeta
+
+
+async def main():
+    """Demo the simple query API."""
+    # Load API keys
+    load_dotenv()
+
+    # Create a conversation with some sample content
+    print("Creating conversation...")
+    conv = await create_conversation(
+        None,
+        TranscriptMessage,
+        name="Demo Conversation",
+    )
+
+    # Add some sample messages
+    messages = [
+        TranscriptMessage(
+            text_chunks=["Welcome to the Python programming tutorial."],
+            metadata=TranscriptMessageMeta(speaker="Instructor"),
+        ),
+        TranscriptMessage(
+            text_chunks=["Today we'll learn about async/await in Python."],
+            metadata=TranscriptMessageMeta(speaker="Instructor"),
+        ),
+        TranscriptMessage(
+            text_chunks=[
+                "Python is a great language for beginners and experts alike."
+            ],
+            metadata=TranscriptMessageMeta(speaker="Instructor"),
+        ),
+        TranscriptMessage(
+            text_chunks=["The async keyword is used to define asynchronous functions."],
+            metadata=TranscriptMessageMeta(speaker="Instructor"),
+        ),
+        TranscriptMessage(
+            text_chunks=[
+                "You use await to wait for asynchronous operations to complete."
+            ],
+            metadata=TranscriptMessageMeta(speaker="Instructor"),
+        ),
+    ]
+
+    print("Adding messages and building indexes...")
+    result = await conv.add_messages_with_indexing(messages)
+    print(f"Conversation ready with {await conv.messages.size()} messages.")
+    print(f"Added {result.messages_added} messages, {result.semrefs_added} semantic refs")
+    
+    # Check indexes
+    if conv.secondary_indexes:
+        if conv.secondary_indexes.message_index:
+            msg_index_size = await conv.secondary_indexes.message_index.size()
+            print(f"Message index has {msg_index_size} entries")
+    print()
+
+    # Interactive query loop
+    print("You can now ask questions about the conversation.")
+    print("Type 'quit' or 'exit' to stop.\n")
+
+    while True:
+        try:
+            question: str = input("typeagent> ")
+            if not question.strip():
+                continue
+            if question.strip().lower() in ("quit", "exit", "q"):
+                break
+
+            # This is the simple API pattern
+            answer: str = await conv.query(question)
+            print(answer)
+            print()
+
+        except EOFError:
+            print()
+            break
+        except KeyboardInterrupt:
+            print("\nExiting...")
+            break
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

test/test_query_method.py

@@ -0,0 +1,85 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Test the conversation.query() method."""
+
+import pytest
+
+from typeagent import create_conversation
+from typeagent.aitools.embeddings import AsyncEmbeddingModel, TEST_MODEL_NAME
+from typeagent.aitools.utils import load_dotenv
+from typeagent.knowpro.convsettings import ConversationSettings
+from typeagent.transcripts.transcript import TranscriptMessage, TranscriptMessageMeta
+
+
+@pytest.fixture(scope="session")
+def needs_auth() -> None:
+    """Load environment variables for authentication."""
+    load_dotenv()
+
+
+@pytest.mark.asyncio
+async def test_query_method_basic(needs_auth: None):
+    """Test the basic query method workflow."""
+    # Create a conversation with some test data
+    test_model = AsyncEmbeddingModel(model_name=TEST_MODEL_NAME)
+    settings = ConversationSettings(model=test_model)
+    conversation = await create_conversation(
+        None,
+        TranscriptMessage,
+        name="Test Conversation",
+        settings=settings,
+    )
+
+    # Add some test messages
+    messages = [
+        TranscriptMessage(
+            text_chunks=["Welcome to the Python programming tutorial."],
+            metadata=TranscriptMessageMeta(speaker="Instructor"),
+        ),
+        TranscriptMessage(
+            text_chunks=["Today we'll learn about async/await in Python."],
+            metadata=TranscriptMessageMeta(speaker="Instructor"),
+        ),
+        TranscriptMessage(
+            text_chunks=["Python is a great language for beginners."],
+            metadata=TranscriptMessageMeta(speaker="Instructor"),
+        ),
+    ]
+
+    await conversation.add_messages_with_indexing(messages)
+
+    # Test the query method
+    answer = await conversation.query("What programming language is discussed?")
+
+    # Verify we got a response (content depends on indexing and LLM behavior)
+    assert isinstance(answer, str)
+    assert len(answer) > 0
+    # The answer should either mention Python or indicate no answer was found
+    # Both are valid since indexing might not extract all knowledge
+    assert (
+        "python" in answer.lower()
+        or "no answer" in answer.lower()
+        or "unable to find" in answer.lower()
+    )
+
+
+@pytest.mark.asyncio
+async def test_query_method_empty_conversation(needs_auth: None):
+    """Test query method on an empty conversation."""
+    test_model = AsyncEmbeddingModel(model_name=TEST_MODEL_NAME)
+    settings = ConversationSettings(model=test_model)
+    conversation = await create_conversation(
+        None,
+        TranscriptMessage,
+        name="Empty Conversation",
+        settings=settings,
+    )
+
+    # Query should handle empty conversation gracefully
+    answer = await conversation.query("What was discussed?")
+
+    assert isinstance(answer, str)
+    assert len(answer) > 0
+    # Should indicate no answer found or no relevant information
+    assert "no answer" in answer.lower() or "unable to find" in answer.lower()