[python/knowpro] Update interfaces.py to latest interfaces.ts; minor …

…tweaks (#792)

python/knowpro/README.md

@@ -1,11 +1,12 @@
-# know_pro
+# knowpro
 
-**Experimental prototype**: Working toward a shared understanding of the MVP for structured RAG.
+**Experimental prototype**: Working toward a shared understanding
+of the MVP for structured RAG.
 
 **Sample code**
 
 This is an in-progress project aiming at a Pythonic translation of
-`TypeAgent/ts/packages/know_pro` to Python. (Pythonic because it
+`TypeAgent/ts/packages/knowPro` to Python. (Pythonic because it
 uses Python conventions and types as appropriate.)
 
 - Python class names correspond 1:1 to TS interface or type names.

python/knowpro/interfaces.py

@@ -9,8 +9,9 @@
 # - I rearranged the order in some cases to ensure def-before-ref.
 # - I translated readonly to @property.
 
-from typing import Any, Callable, Literal, Protocol, runtime_checkable, Sequence
+from collections.abc import Sequence
 from datetime import datetime as Date
+from typing import Any, Callable, Literal, Protocol, runtime_checkable
 
 from . import kplib
 
@@ -25,7 +26,10 @@ def get_knowledge(self) -> kplib.KnowledgeResponse:
 @runtime_checkable
 class DeletionInfo(Protocol):
     timestamp: str
-    reason: str | None
+    reason: str | None = None
+
+
+type MessageIndex = int
 
 
 @runtime_checkable
@@ -49,6 +53,12 @@ class ScoredSemanticRef(Protocol):
     score: float
 
 
+@runtime_checkable
+class ScoredMessageIndex(Protocol):
+    message_index: MessageIndex
+    score: float
+
+
 @runtime_checkable
 class ITermToSemanticRefIndex(Protocol):
     def getTerms(self) -> Sequence[str]:
@@ -71,9 +81,6 @@ def lookupTerm(self, term: str) -> Sequence[ScoredSemanticRef] | None:
 type KnowledgeType = Literal["entity", "action", "topic", "tag"]
 
 
-type MessageIndex = int
-
-
 @runtime_checkable
 class Topic(Protocol):
     text: str
@@ -287,12 +294,12 @@ class ITermToSemanticRefIndexData(Protocol):
 
 
 @runtime_checkable
-class IConversationData[TMessage](Protocol):
+class IConversationData[TMessage = Any](Protocol):
     name_tag: str
     messages: Sequence[TMessage]
     tags: Sequence[str]
     semantic_refs: Sequence[SemanticRef]
-    semantic_index_data: ITermToSemanticRefIndexData | None
+    semantic_index_data: ITermToSemanticRefIndexData | None = None
 
 
 # ------------------------
@@ -305,8 +312,8 @@ class IndexingEventHandlers(Protocol):
     on_knowledge_xtracted: (
         Callable[
             [
-                TextLocation,
-                kplib.KnowledgeResponse,
+                TextLocation,  # chunk
+                kplib.KnowledgeResponse,  # knowledge_result
             ],
             bool,
         ]
@@ -315,9 +322,9 @@ class IndexingEventHandlers(Protocol):
     on_embeddings_created: (
         Callable[
             [
-                Sequence[str],
-                Sequence[str],
-                int,
+                Sequence[str],  # source_texts
+                Sequence[str],  # batch
+                int,  # batch_start_at
             ],
             bool,
         ]

python/knowpro/kplib.py

@@ -28,22 +28,21 @@ class Facet(Protocol):
     value: Value
 
 
+# Specific, tangible people, places, institutions or things only
 @runtime_checkable
 class ConcreteEntity(Protocol):
-    """Specific, tangible people, places, institutions or things only."""
-
-    # the name of the entity or thing such as "Bach", "Great Gatsby",
+    # The name of the entity or thing such as "Bach", "Great Gatsby",
     # "frog" or "piano".
     name: str
-    # the types of the entity such as "speaker", "person", "artist", "animal",
+    # 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.
     type: list[str]
     # 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".
-    facets: list[Facet] | None
+    facets: list[Facet] | None = None
 
 
 @runtime_checkable
@@ -63,22 +62,21 @@ class Action(Protocol):
     subject_entity_name: str | Literal["none"]
     object_entity_name: str | Literal["none"]
     indirect_object_entity_name: str | Literal["none"]
-    params: list[str | ActionParam] | None
-    # If the action implies this additional facet or property of the subject entity,
-    # such as hobbies, activities, interests, personality.
-    subject_entity_facet: Facet | None
+    params: list[str | ActionParam] | None = None
+    # If the action implies this additional facet or property of the
+    # subject entity, such as hobbies, activities, interests, personality.
+    subject_entity_facet: Facet | None = None
 
 
+# Detailed and comprehensive knowledge response.
 @runtime_checkable
 class KnowledgeResponse(Protocol):
-    """Detailed and comprehensive knowledge response."""
-
-    # The 'subjectEntityName' and 'objectEntityName' must correspond to the
-    # 'name' of an entity listed in the 'entities' array.
     entities: list[ConcreteEntity]
+    # The 'subject_entity_name' and 'object_entity_name' must correspond
+    # to the 'name' of an entity listed in the 'entities' array.
     actions: list[Action]
     # Some actions can ALSO be expressed in a reverse way...
-    # e.g. (A give to B) --> (B receive from A) and vice versa.
+    # 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.
     inverse_actions: list[Action]
     # Detailed, descriptive topics and keywords.