GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/TypeAgent

Public

mirrored from https://github.com/microsoft/TypeAgentAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
d0d089056c778d2bf73b1b50efa558f565a9f47d

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

TypeAgent/python/knowpro

python/knowpro/interfaces.py

338lines · modecode

RawDownload
Latest commit unavailable.
1# Copyright (c) Microsoft Corporation.
2# Licensed under the MIT License.
3
4# TODO:
5# - See TODOs in kplib.py.
6#
7# NOTE:
8# - I took some liberty with index types and made them int.
9# - I rearranged the order in some cases to ensure def-before-ref.
10# - I translated readonly to @property.
11
12from collections.abc import Sequence
13from datetime import datetime as Date
14from typing import Any, Callable, Literal, Protocol, runtime_checkable
15
16from . import kplib
17
18
19# An object that can provide a KnowledgeResponse structure.
20@runtime_checkable
21class IKnowledgeSource(Protocol):
22 def get_knowledge(self) -> kplib.KnowledgeResponse:
23 raise NotImplementedError
24
25
26@runtime_checkable
27class DeletionInfo(Protocol):
28 timestamp: str
29 reason: str | None = None
30
31
32type MessageIndex = int
33
34
35@runtime_checkable
36class IMessage[TMeta: IKnowledgeSource = Any](Protocol):
37 # The text of the message, split into chunks.
38 text_chunks: Sequence[str]
39 # For example, e-mail has subject, from and to fields;
40 # a chat message has a sender and a recipient.
41 metadata: TMeta
42 timestamp: str | None = None
43 tags: Sequence[str]
44 deletion_info: DeletionInfo | None = None
45
46
47type SemanticRefIndex = int
48
49
50@runtime_checkable
51class ScoredSemanticRef(Protocol):
52 semantic_ref_index: SemanticRefIndex
53 score: float
54
55
56@runtime_checkable
57class ScoredMessageIndex(Protocol):
58 message_index: MessageIndex
59 score: float
60
61
62@runtime_checkable
63class ITermToSemanticRefIndex(Protocol):
64 def getTerms(self) -> Sequence[str]:
65 raise NotImplementedError
66
67 def addTerm(
68 self,
69 term: str,
70 semantic_ref_index: SemanticRefIndex | ScoredSemanticRef,
71 ) -> None:
72 raise NotImplementedError
73
74 def removeTerm(self, term: str, semantic_ref_index: SemanticRefIndex) -> None:
75 raise NotImplementedError
76
77 def lookupTerm(self, term: str) -> Sequence[ScoredSemanticRef] | None:
78 raise NotImplementedError
79
80
81type KnowledgeType = Literal["entity", "action", "topic", "tag"]
82
83
84@runtime_checkable
85class Topic(Protocol):
86 text: str
87
88
89@runtime_checkable
90class Tag(Protocol):
91 text: str
92
93
94type Knowledge = kplib.ConcreteEntity | kplib.Action | Topic | Tag
95
96
97@runtime_checkable
98class TextLocation(Protocol):
99 # The index of the message.
100 message_index: MessageIndex
101 # The index of the chunk.
102 chunkIndex: int | None
103 # The index of the character within the chunk.
104 charIndex: int | None
105
106
107# A text range within a session.
108@runtime_checkable
109class TextRange(Protocol):
110 # The start of the range.
111 start: TextLocation
112 # The end of the range (exclusive).
113 end: TextLocation | None
114
115
116@runtime_checkable
117class SemanticRef(Protocol):
118 semantic_ref_index: SemanticRefIndex
119 range: TextRange
120 knowledge_type: KnowledgeType
121 knowledge: Knowledge
122
123
124@runtime_checkable
125class DateRange(Protocol):
126 start: Date
127 # Inclusive.
128 end: Date | None
129
130
131@runtime_checkable
132class Term(Protocol):
133 text: str
134 # Optional weighting for these matches.
135 weight: float | None
136
137
138@runtime_checkable
139class ScoredKnowledge(Protocol):
140 knowledge_type: KnowledgeType
141 knowledge: Knowledge
142 score: float
143
144
145# Allows for faster retrieval of name, value properties
146@runtime_checkable
147class IPropertyToSemanticRefIndex(Protocol):
148 def get_values(self) -> Sequence[str]:
149 raise NotImplementedError
150
151 def add_property(
152 self,
153 property_name: str,
154 value: str,
155 semantic_ref_index: SemanticRefIndex | ScoredSemanticRef,
156 ) -> None:
157 raise NotImplementedError
158
159 def lookup_property(
160 self, property_name: str, value: str
161 ) -> Sequence[ScoredSemanticRef] | None:
162 raise NotImplementedError
163
164
165@runtime_checkable
166class TimestampedTextRange(Protocol):
167 timestamp: str
168 range: TextRange
169
170
171# Return text ranges in the given date range.
172@runtime_checkable
173class ITimestampToTextRangeIndex(Protocol):
174 def add_timestamp(self, message_index: MessageIndex, timestamp: str) -> None:
175 raise NotImplementedError
176
177 def add_timestamps(
178 self, message_imestamps: Sequence[tuple[MessageIndex, str]]
179 ) -> bool:
180 raise NotImplementedError
181
182 def lookup_range(self, date_range: DateRange) -> Sequence[TimestampedTextRange]:
183 raise NotImplementedError
184
185
186@runtime_checkable
187class ITermToRelatedTerms(Protocol):
188 def lookup_term(self, text: str) -> Sequence[Term] | None:
189 raise NotImplementedError
190
191
192@runtime_checkable
193class ITermToRelatedTermsFuzzy(Protocol):
194 async def add_terms(
195 self, terms: Sequence[str], event_handler: "IndexingEventHandlers | None" = None
196 ) -> None:
197 raise NotImplementedError
198
199 async def lookup_term(
200 self,
201 text: str,
202 max_matches: int | None = None,
203 threshold_score: float | None = None,
204 ) -> Sequence[Term]:
205 raise NotImplementedError
206
207 async def lookup_terms(
208 self,
209 text_array: Sequence[str],
210 max_matches: int | None = None,
211 threshold_score: float | None = None,
212 ) -> Sequence[Sequence[Term]]:
213 raise NotImplementedError
214
215
216@runtime_checkable
217class ITermToRelatedTermsIndex(Protocol):
218 @property
219 def aliases(self) -> ITermToRelatedTerms | None:
220 raise NotImplementedError
221
222 @property
223 def fuzzy_index(self) -> ITermToRelatedTermsFuzzy | None:
224 raise NotImplementedError
225
226
227# A Thread is a set of text ranges in a conversation.
228@runtime_checkable
229class Thread(Protocol):
230 description: str
231 ranges: Sequence[TextRange]
232
233
234type ThreadIndex = int
235
236
237@runtime_checkable
238class ScoredThreadIndex(Protocol):
239 thread_index: ThreadIndex
240 score: float
241
242
243@runtime_checkable
244class IConversationThreads(Protocol):
245 @property
246 def threads(self) -> Sequence[Thread]:
247 raise NotImplementedError
248
249 async def add_thread(self, thread: Thread) -> None:
250 raise NotImplementedError
251
252 async def lookup_thread(
253 self,
254 thread_description: str,
255 max_matches: int | None = None,
256 threshold_score: float | None = None,
257 ) -> Sequence[ScoredThreadIndex] | None:
258 raise NotImplementedError
259
260
261@runtime_checkable
262class IConversationSecondaryIndexes(Protocol):
263 property_to_semantic_ref_index: IPropertyToSemanticRefIndex | None
264 timestampIndex: ITimestampToTextRangeIndex | None
265 termToRelatedTermsIndex: ITermToRelatedTermsIndex | None
266 threads: IConversationThreads | None
267
268
269@runtime_checkable
270class IConversation[TMeta: IKnowledgeSource = Any](Protocol):
271 name_tag: str
272 tags: Sequence[str]
273 messages: Sequence[IMessage[TMeta]]
274 semantic_refs: Sequence[SemanticRef] | None
275 semantic_ref_index: ITermToSemanticRefIndex | None
276 secondaryIndexes: IConversationSecondaryIndexes | None
277
278
279# ------------------------
280# Serialization formats
281# ------------------------
282
283
284@runtime_checkable
285class ITermToSemanticRefIndexItem(Protocol):
286 term: str
287 semantic_ref_indices: Sequence[ScoredSemanticRef]
288
289
290# Persistent form of a term index.
291@runtime_checkable
292class ITermToSemanticRefIndexData(Protocol):
293 items: Sequence[ITermToSemanticRefIndexItem]
294
295
296@runtime_checkable
297class IConversationData[TMessage = Any](Protocol):
298 name_tag: str
299 messages: Sequence[TMessage]
300 tags: Sequence[str]
301 semantic_refs: Sequence[SemanticRef]
302 semantic_index_data: ITermToSemanticRefIndexData | None = None
303
304
305# ------------------------
306# Indexing
307# ------------------------
308
309
310@runtime_checkable
311class IndexingEventHandlers(Protocol):
312 on_knowledge_xtracted: (
313 Callable[
314 [
315 TextLocation, # chunk
316 kplib.KnowledgeResponse, # knowledge_result
317 ],
318 bool,
319 ]
320 | None
321 ) = None
322 on_embeddings_created: (
323 Callable[
324 [
325 Sequence[str], # source_texts
326 Sequence[str], # batch
327 int, # batch_start_at
328 ],
329 bool,
330 ]
331 | None
332 ) = None
333
334
335@runtime_checkable
336class IndexingResults(Protocol):
337 chunksIndexedUpto: TextLocation | None = None
338 error: str | None = None
339