typeagent-py 0.1.0__py3-none-any.whl

typeagent/knowpro/knowledge.py

@@ -0,0 +1,88 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from typechat import Result, TypeChatLanguageModel
+
+from . import convknowledge
+from . import kplib
+
+
+def create_knowledge_extractor(
+    chat_model: TypeChatLanguageModel | None = None,
+) -> convknowledge.KnowledgeExtractor:
+    """Create a knowledge extractor using the given Chat Model."""
+    chat_model = chat_model or convknowledge.create_typechat_model()
+    extractor = convknowledge.KnowledgeExtractor(
+        chat_model, max_chars_per_chunk=4096, merge_action_knowledge=False
+    )
+    return extractor
+
+
+async def extract_knowledge_from_text(
+    knowledge_extractor: convknowledge.KnowledgeExtractor,
+    text: str,
+    max_retries: int,
+) -> Result[kplib.KnowledgeResponse]:
+    """Extract knowledge from a single text input with retries."""
+    # TODO: Add a retry mechanism to handle transient errors.
+    return await knowledge_extractor.extract(text)
+
+
+async def extract_knowledge_from_text_batch(
+    knowledge_extractor: convknowledge.KnowledgeExtractor,
+    text_batch: list[str],
+    concurrency: int = 2,
+    max_retries: int = 3,
+) -> list[Result[kplib.KnowledgeResponse]]:
+    """Extract knowledge from a batch of text inputs concurrently."""
+    # TODO: Use concurrency.
+    results: list[Result[kplib.KnowledgeResponse]] = []
+    for text in text_batch:
+        result = await extract_knowledge_from_text(
+            knowledge_extractor, text, max_retries
+        )
+        results.append(result)
+    return results
+
+
+def merge_concrete_entities(
+    entities: list[kplib.ConcreteEntity],
+) -> list[kplib.ConcreteEntity]:
+    """Merge a list of concrete entities into a single list of merged entities."""
+    raise NotImplementedError("TODO")
+    # merged_entities = concrete_to_merged_entities(entities)
+
+    # merged_concrete_entities = []
+    # for merged_entity in merged_entities.values():
+    #     merged_concrete_entities.append(merged_to_concrete_entity(merged_entity))
+    # return merged_concrete_entities
+
+
+def merge_topics(topics: list[str]) -> list[str]:
+    """Merge a list of topics into a unique list of topics."""
+    # TODO: Preserve order of first occurrence?
+    merged_topics = set(topics)
+    return list(merged_topics)
+
+
+async def extract_knowledge_for_text_batch_q(
+    knowledge_extractor: convknowledge.KnowledgeExtractor,
+    text_batch: list[str],
+    concurrency: int = 2,
+    max_retries: int = 3,
+) -> list[Result[kplib.KnowledgeResponse]]:
+    """Extract knowledge for a batch of text inputs using a task queue."""
+    raise NotImplementedError("TODO")
+    # TODO: BatchTask etc.
+    # task_batch = [BatchTask(task=text) for text in text_batch]
+
+    # await run_in_batches(
+    #     task_batch,
+    #     lambda text: extract_knowledge_from_text(knowledge_extractor, text, max_retries),
+    #     concurrency,
+    # )
+
+    # results = []
+    # for task in task_batch:
+    #     results.append(task.result if task.result else Failure("No result"))
+    # return results

typeagent/knowpro/kplib.py

@@ -0,0 +1,125 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""This file defines the data types generated by knowledge extraction.
+
+It also doubles as the schema for the extraction process.
+Comments that should go into the schema are in docstrings and Doc() annotations.
+"""
+
+from pydantic.dataclasses import dataclass
+from pydantic import Field, AliasChoices
+from typing import Annotated, ClassVar, Literal
+from typing_extensions import Doc
+
+from .field_helpers import CamelCaseField
+
+
+@dataclass
+class Quantity:
+    amount: float
+    units: str
+
+    def __str__(self) -> str:
+        return f"{self.amount:g} {self.units}"
+
+
+type Value = str | float | bool | Quantity
+
+
+@dataclass
+class Facet:
+    name: str
+    value: Annotated[Value, Doc("Very concise values.")]
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.name!r}, {self.value!r})"
+
+
+@dataclass
+class ConcreteEntity:
+    """Specific, tangible people, places, institutions or things only."""
+
+    knowledge_type: ClassVar[Literal["entity"]] = "entity"
+
+    name: Annotated[
+        str,
+        Doc(
+            "The name of the entity or thing such as 'Bach', 'Great Gatsby', "
+            "'frog' or 'piano'."
+        ),
+    ]
+    type: Annotated[
+        list[str],
+        Doc(
+            "The types of the entity such as 'speaker', 'person', 'artist', "
+            "'animal', 'object', 'instrument', 'school', 'room', 'museum', 'food' etc. "
+            "An entity can have multiple types; entity types should be single words."
+        ),
+    ]
+    facets: Annotated[
+        list[Facet] | None,
+        Doc(
+            "A specific, inherent, defining, or non-immediate facet of the entity "
+            "such as 'blue', 'old', 'famous', 'sister', 'aunt_of', 'weight: 4 kg'. "
+            "Trivial actions or state changes are not facets. "
+            "Facets are concise 'properties'."
+        ),
+    ] = None
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.name!r}, {self.type}, {self.facets})"
+
+
+@dataclass
+class ActionParam:
+    name: str
+    value: Value
+
+
+type VerbTense = Literal["past", "present", "future"]
+
+
+@dataclass
+class Action:
+    knowledge_type: ClassVar[Literal["action"]] = "action"
+
+    verbs: Annotated[list[str], Doc("Each verb is typically a word.")]
+    verb_tense: VerbTense = CamelCaseField("The tense of the verb")
+    subject_entity_name: str | Literal["none"] = CamelCaseField(
+        "The name of the subject entity", default="none"
+    )
+    object_entity_name: str | Literal["none"] = CamelCaseField(
+        "The name of the object entity", default="none"
+    )
+    indirect_object_entity_name: str | Literal["none"] = CamelCaseField(
+        "The name of the indirect object entity", default="none"
+    )
+    params: list[str | ActionParam] | None = None
+    subject_entity_facet: Facet | None = CamelCaseField(
+        "If the action implies this additional facet or property of the subject entity, such as hobbies, activities, interests, personality",
+        default=None,
+    )
+
+
+@dataclass
+class KnowledgeResponse:
+    """Detailed and comprehensive knowledge response."""
+
+    entities: list[ConcreteEntity]
+    actions: Annotated[
+        list[Action],
+        Doc(
+            "The 'subject_entity_name' and 'object_entity_name' must correspond "
+            "to the 'name' of an entity listed in the 'entities' array."
+        ),
+    ]
+    inverse_actions: Annotated[
+        list[Action],
+        Doc(
+            "Some actions can ALSO be expressed in a reverse way... "
+            "E.g. (A give to B) --> (B receive from A) and vice versa. "
+            "If so, also return the reverse form of the action, full filled out."
+        ),
+    ]
+    topics: Annotated[list[str], Doc("Detailed, descriptive topics and keywords.")]