typeagent-py 0.1.0__py3-none-any.whl

typeagent/knowpro/common.py

@@ -0,0 +1,9 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from .interfaces import SearchTerm
+
+
+def is_search_term_wildcard(search_term: SearchTerm) -> bool:
+    """Check if a search term is a wildcard."""
+    return search_term.term.text == "*"

typeagent/knowpro/convknowledge.py

@@ -0,0 +1,112 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+import asyncio
+from dataclasses import dataclass, field
+import os
+
+import typechat
+
+from ..aitools import auth
+from . import kplib
+from .interfaces import IKnowledgeExtractor
+
+
+# TODO: Move ModelWrapper and create_typechat_model() to aitools package.
+
+
+class ModelWrapper(typechat.TypeChatLanguageModel):
+    def __init__(
+        self,
+        base_model: typechat.TypeChatLanguageModel,
+        token_provider: auth.AzureTokenProvider,
+    ):
+        self.base_model = base_model
+        self.token_provider = token_provider
+
+    async def complete(
+        self, prompt: str | list[typechat.PromptSection]
+    ) -> typechat.Result[str]:
+        if self.token_provider.needs_refresh():
+            loop = asyncio.get_running_loop()
+            api_key = await loop.run_in_executor(
+                None, self.token_provider.refresh_token
+            )
+            env: dict[str, str | None] = dict(os.environ)
+            key_name = "AZURE_OPENAI_API_KEY"
+            env[key_name] = api_key
+            self.base_model = typechat.create_language_model(env)
+        return await self.base_model.complete(prompt)
+
+
+def create_typechat_model() -> typechat.TypeChatLanguageModel:
+    env: dict[str, str | None] = dict(os.environ)
+    key_name = "AZURE_OPENAI_API_KEY"
+    key = env.get(key_name)
+    shared_token_provider: auth.AzureTokenProvider | None = None
+    if key is not None and key.lower() == "identity":
+        shared_token_provider = auth.get_shared_token_provider()
+        env[key_name] = shared_token_provider.get_token()
+    model = typechat.create_language_model(env)
+    if shared_token_provider is not None:
+        model = ModelWrapper(model, shared_token_provider)
+    return model
+
+
+@dataclass
+class KnowledgeExtractor:
+    model: typechat.TypeChatLanguageModel = field(default_factory=create_typechat_model)
+    max_chars_per_chunk: int = 2048
+    merge_action_knowledge: bool = True
+    # Not in the signature:
+    translator: typechat.TypeChatJsonTranslator[kplib.KnowledgeResponse] = field(
+        init=False
+    )
+
+    def __post_init__(self):
+        self.translator = self.create_translator(self.model)
+
+    # TODO: Use max_chars_per_chunk and merge_action_knowledge.
+
+    async def extract(self, message: str) -> typechat.Result[kplib.KnowledgeResponse]:
+        result = await self.translator.translate(message)
+        if isinstance(result, typechat.Success):
+            if self.merge_action_knowledge:
+                self.merge_action_knowledge_into_response(result.value)
+        return result
+
+    def create_translator(
+        self, model: typechat.TypeChatLanguageModel
+    ) -> typechat.TypeChatJsonTranslator[kplib.KnowledgeResponse]:
+        schema = kplib.KnowledgeResponse
+        type_name = "KnowledgeResponse"
+        validator = typechat.TypeChatValidator[kplib.KnowledgeResponse](schema)
+        translator = typechat.TypeChatJsonTranslator[kplib.KnowledgeResponse](
+            model, validator, kplib.KnowledgeResponse
+        )
+        schema_text = translator.schema_str.rstrip()
+
+        def create_request_prompt(intent: str) -> str:
+            return (
+                f"You are a service that translates user messages in a conversation "
+                + f'into JSON objects of type "{type_name}" '
+                + f"according to the following TypeScript definitions:\n"
+                + f"```\n"
+                + f"{schema_text}\n"
+                + f"```\n"
+                + f"The following are messages in a conversation:\n"
+                + f'"""\n'
+                + f"{intent}\n"
+                + f'"""\n'
+                + f"The following is the user request translated into a JSON object "
+                + f"with 2 spaces of indentation and no properties with the value undefined:\n"
+            )
+
+        translator._create_request_prompt = create_request_prompt
+        return translator
+
+    def merge_action_knowledge_into_response(
+        self, knowledge: kplib.KnowledgeResponse
+    ) -> None:
+        """Merge action knowledge into a single knowledge object."""
+        raise NotImplementedError("TODO")

typeagent/knowpro/convsettings.py

@@ -0,0 +1,94 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..aitools.embeddings import AsyncEmbeddingModel
+from ..aitools.vectorbase import TextEmbeddingIndexSettings
+from .interfaces import IKnowledgeExtractor, IStorageProvider
+
+
+@dataclass
+class MessageTextIndexSettings:
+    embedding_index_settings: TextEmbeddingIndexSettings
+
+    def __init__(self, embedding_index_settings: TextEmbeddingIndexSettings):
+        self.embedding_index_settings = embedding_index_settings
+
+
+@dataclass
+class RelatedTermIndexSettings:
+    embedding_index_settings: TextEmbeddingIndexSettings
+
+    def __init__(self, embedding_index_settings: TextEmbeddingIndexSettings):
+        self.embedding_index_settings = embedding_index_settings
+
+
+@dataclass
+class SemanticRefIndexSettings:
+    batch_size: int
+    auto_extract_knowledge: bool
+    knowledge_extractor: IKnowledgeExtractor | None = None
+
+
+class ConversationSettings:
+    """Settings for conversation processing and indexing."""
+
+    def __init__(
+        self,
+        model: AsyncEmbeddingModel | None = None,
+        storage_provider: IStorageProvider | None = None,
+    ):
+        # All settings share the same model, so they share the embedding cache.
+        model = model or AsyncEmbeddingModel()
+        self.embedding_model = model
+        min_score = 0.85
+        self.related_term_index_settings = RelatedTermIndexSettings(
+            TextEmbeddingIndexSettings(model, min_score=min_score, max_matches=50)
+        )
+        self.thread_settings = TextEmbeddingIndexSettings(model, min_score=min_score)
+        self.message_text_index_settings = MessageTextIndexSettings(
+            TextEmbeddingIndexSettings(model, min_score=min_score)
+        )
+        self.semantic_ref_index_settings = SemanticRefIndexSettings(
+            batch_size=10,
+            auto_extract_knowledge=False,
+        )
+
+        # Storage provider will be created lazily if not provided
+        self._storage_provider: IStorageProvider | None = storage_provider
+        self._storage_provider_created = storage_provider is not None
+
+    @property
+    def storage_provider(self) -> IStorageProvider:
+        if not self._storage_provider_created:
+            raise RuntimeError(
+                "Storage provider not initialized. Use await ConversationSettings.get_storage_provider() "
+                "or provide storage_provider in constructor."
+            )
+        assert (
+            self._storage_provider is not None
+        ), "Storage provider should be set when _storage_provider_created is True"
+        return self._storage_provider
+
+    @storage_provider.setter
+    def storage_provider(self, value: IStorageProvider) -> None:
+        self._storage_provider = value
+        self._storage_provider_created = True
+
+    async def get_storage_provider(self) -> IStorageProvider:
+        """Get or create the storage provider asynchronously."""
+        if not self._storage_provider_created:
+            from ..storage.memory import MemoryStorageProvider
+
+            self._storage_provider = MemoryStorageProvider(
+                message_text_settings=self.message_text_index_settings,
+                related_terms_settings=self.related_term_index_settings,
+            )
+            self._storage_provider_created = True
+        assert (
+            self._storage_provider is not None
+        ), "Storage provider should be set after creation"
+        return self._storage_provider

typeagent/knowpro/convutils.py

@@ -0,0 +1,49 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+import typechat
+
+from .convsettings import ConversationSettings
+from .interfaces import (
+    DateRange,
+    Datetime,
+    IConversation,
+    IMessage,
+    ITermToSemanticRefIndex,
+)
+
+
+async def get_time_range_prompt_section_for_conversation[
+    TMessage: IMessage, TIndex: ITermToSemanticRefIndex
+](
+    conversation: IConversation[TMessage, TIndex],
+) -> typechat.PromptSection | None:
+    time_range = await get_time_range_for_conversation(conversation)
+    if time_range is not None:
+        start = time_range.start.replace(tzinfo=None).isoformat()
+        end = (
+            time_range.end.replace(tzinfo=None).isoformat() if time_range.end else "now"
+        )
+        return typechat.PromptSection(
+            role="system",
+            content=f"ONLY IF user request explicitly asks for time ranges, "
+            f'THEN use the CONVERSATION TIME RANGE: "{start} to {end}"',
+        )
+
+
+async def get_time_range_for_conversation[
+    TMessage: IMessage, TIndex: ITermToSemanticRefIndex
+](
+    conversation: IConversation[TMessage, TIndex],
+) -> DateRange | None:
+    messages = conversation.messages
+    size = await messages.size()
+    if size > 0:
+        start = (await messages.get_item(0)).timestamp
+        if start is not None:
+            end = (await messages.get_item(size - 1)).timestamp
+            return DateRange(
+                start=Datetime.fromisoformat(start),
+                end=Datetime.fromisoformat(end) if end else None,
+            )
+    return None

typeagent/knowpro/date_time_schema.py

@@ -0,0 +1,32 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from pydantic.dataclasses import dataclass
+from typing import Annotated
+from typing_extensions import Doc
+
+
+@dataclass
+class DateVal:
+    day: int
+    month: int
+    year: int
+
+
+@dataclass
+class TimeVal:
+    hour: Annotated[int, Doc("In 24 hour form")]
+    minute: int
+    seconds: int
+
+
+@dataclass
+class DateTime:
+    date: DateVal
+    time: TimeVal | None = None
+
+
+@dataclass
+class DateTimeRange:
+    start_date: DateTime
+    stop_date: DateTime | None = None

typeagent/knowpro/field_helpers.py

@@ -0,0 +1,87 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from dataclasses import MISSING
+from typing import Any
+
+from pydantic import Field, AliasChoices
+from pydantic.alias_generators import to_camel
+
+
+def CamelCaseField(
+    description: str | None = None,
+    *,
+    field_name: str | None = None,
+    default: Any = MISSING,
+    default_factory: Any = MISSING,
+) -> Any:
+    """
+    Helper function to create a Field with camelCase serialization alias.
+
+    Args:
+        description: The field description
+        field_name: The snake_case field name (if provided, creates Field directly)
+        default: The default value for the field (optional)
+        default_factory: The default factory for the field (optional)
+
+    Returns:
+        If field_name is provided: A Field with serialization_alias set to the camelCase version
+        Otherwise: A descriptor that will create a Field with serialization_alias set to the camelCase version
+        of the field name and validation_alias set to accept both snake_case and camelCase versions.
+
+    Note: For fields ending with underscore (like 'from_'), the underscore is removed in the camelCase version.
+    """
+
+    # If field_name is provided, create the Field directly
+    if field_name is not None:
+        clean_name = field_name.rstrip("_")
+        camel_name = to_camel(clean_name)
+
+        field_kwargs = {
+            "description": description,
+            "serialization_alias": camel_name,
+            "validation_alias": AliasChoices(field_name, camel_name),
+        }
+
+        if default is not MISSING:
+            field_kwargs["default"] = default
+        elif default_factory is not MISSING:
+            field_kwargs["default_factory"] = default_factory
+
+        return Field(**field_kwargs)
+
+        return Field(**field_kwargs)
+
+    # Otherwise, use the descriptor approach for backward compatibility
+    class CamelCaseFieldDescriptor:
+        def __init__(
+            self,
+            description: str | None = None,
+            default: Any = MISSING,
+            default_factory: Any = MISSING,
+        ):
+            self.description = description
+            self.default = default
+            self.default_factory = default_factory
+
+        def __set_name__(self, owner, name):
+            # Replace ourselves with the actual Field when the field name is known
+            # Handle trailing underscore (like from_ -> from)
+            clean_name = name.rstrip("_")
+            camel_name = to_camel(clean_name)
+
+            field_kwargs = {
+                "description": self.description,
+                "serialization_alias": camel_name,
+                "validation_alias": AliasChoices(name, camel_name),
+            }
+
+            if self.default is not MISSING:
+                field_kwargs["default"] = self.default
+            elif self.default_factory is not MISSING:
+                field_kwargs["default_factory"] = self.default_factory
+
+            field = Field(**field_kwargs)
+            setattr(owner, name, field)
+
+    return CamelCaseFieldDescriptor(description, default, default_factory)

typeagent/knowpro/fuzzyindex.py

@@ -0,0 +1,144 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from collections.abc import Callable
+
+import numpy as np
+
+from ..aitools.vectorbase import VectorBase, TextEmbeddingIndexSettings, ScoredInt
+from ..aitools.embeddings import NormalizedEmbedding, NormalizedEmbeddings
+
+
+class EmbeddingIndex:
+    """Wrapper around VectorBase."""
+
+    # TODO: Don't use self._vector_base._vectors directly; use VectorBase methods.
+
+    def __init__(
+        self,
+        settings: TextEmbeddingIndexSettings,
+        embeddings: NormalizedEmbeddings | None = None,
+    ):
+        # Use VectorBase for storage and operations on embeddings.
+        self._vector_base = VectorBase(settings)
+
+        # Initialize with embeddings if provided.
+        if embeddings is not None:
+            for embedding in embeddings:
+                self._vector_base.add_embedding(None, embedding)
+
+    def __len__(self) -> int:
+        return len(self._vector_base)
+
+    async def size(self) -> int:
+        return len(self._vector_base)
+
+    async def is_empty(self) -> bool:
+        return len(self._vector_base) == 0
+
+    async def get_embedding(self, key: str, cache: bool = True) -> NormalizedEmbedding:
+        return await self._vector_base.get_embedding(key, cache)
+
+    def get(self, pos: int) -> NormalizedEmbedding:
+        return self._vector_base.get_embedding_at(pos)
+
+    def push(self, embeddings: NormalizedEmbeddings) -> None:
+        self._vector_base.add_embeddings(embeddings)
+
+    async def add_texts(self, texts: list[str]) -> None:
+        await self._vector_base.add_keys(texts)
+
+    # def insert_at(
+    #     self, index: int, embeddings: NormalizedEmbedding | list[NormalizedEmbedding]
+    # ) -> None:
+    #     """Insert one or more embeddings at the specified position.
+
+    #     Args:
+    #         index: Position to insert at
+    #         embeddings: A single embedding or list of embeddings to insert
+    #     """
+    #     # Convert input to list
+    #     emb_list = embeddings if isinstance(embeddings, list) else [embeddings]
+
+    #     # Create a new array with space for the insertions
+    #     old_vectors = self._vector_base._vectors
+    #     size = len(old_vectors)
+
+    #     if index < 0 or index > size:
+    #         raise IndexError(
+    #             f"Index {index} out of bounds for insertion in embedding index of size {size}"
+    #         )
+
+    #     # Convert embeddings to 2D array
+    #     new_vectors = np.vstack([e.reshape(1, -1) for e in emb_list])
+
+    #     # Split and recombine the vectors
+    #     if index == 0:
+    #         result = np.vstack([new_vectors, old_vectors])
+    #     elif index >= size:
+    #         result = np.vstack([old_vectors, new_vectors])
+    #     else:
+    #         result = np.vstack([old_vectors[:index], new_vectors, old_vectors[index:]])
+
+    #     # Update the vector base
+    #     self._vector_base._vectors = result
+
+    def get_indexes_of_nearest(
+        self,
+        embedding: NormalizedEmbedding,
+        max_matches: int | None = None,
+        min_score: float | None = None,
+        predicate: Callable[[int], bool] | None = None,
+    ) -> list[ScoredInt]:
+        return self._vector_base.fuzzy_lookup_embedding(
+            embedding,
+            max_hits=max_matches,
+            min_score=min_score,
+            predicate=predicate,
+        )
+
+    def get_indexes_of_nearest_in_subset(
+        self,
+        embedding: NormalizedEmbedding,
+        ordinals_of_subset: list[int],
+        max_matches: int | None = None,
+        min_score: float | None = None,
+    ) -> list[ScoredInt]:
+        return self._vector_base.fuzzy_lookup_embedding_in_subset(
+            embedding,
+            ordinals_of_subset,
+            max_matches,
+            min_score,
+        )
+
+    # def remove_at(self, pos: int) -> None:
+    #     """Remove the embedding at the specified position.
+
+    #     Args:
+    #         pos: The position to remove
+    #     """
+    #     if 0 <= pos < len(self._vector_base):
+    #         # Create new array without the element at pos
+    #         self._vector_base._vectors = np.delete(
+    #             self._vector_base._vectors, pos, axis=0
+    #         )
+    #     else:
+    #         raise IndexError(
+    #             f"Index {pos} out of bounds for embedding index of size {len(self._vector_base)}"
+    #         )
+
+    def clear(self) -> None:
+        self._vector_base.clear()
+
+    def serialize(self) -> NormalizedEmbeddings:
+        return self._vector_base.serialize()
+
+    def deserialize(self, embeddings: NormalizedEmbedding) -> None:
+        assert isinstance(embeddings, np.ndarray), type(embeddings)
+        assert embeddings.dtype == np.float32, embeddings.dtype
+        assert embeddings.ndim == 2, embeddings.shape
+        assert (
+            embeddings.shape[1] == self._vector_base._embedding_size
+        ), embeddings.shape
+        self.clear()
+        self.push(embeddings)