agentic-composite-memory 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,616 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import hashlib
5
+ import json
6
+ import math
7
+ import os
8
+ import re
9
+ from typing import Any
10
+
11
+ import httpx
12
+
13
+ from .auth import AwsIamDatabaseAuthProvider, CloudAuthProvider
14
+ from .models import (
15
+ CompiledTBox,
16
+ ExtractionPayload,
17
+ )
18
+ from .ports import EmbeddingAdapter, OntologyExtractorAdapter
19
+
20
+
21
+ def _align_vector_dim(vec: list[float], target_dim: int | None) -> list[float]:
22
+ """
23
+ Optionally pads (with zeros) or truncates + L2-renormalizes an embedding vector
24
+ when a model's native dimension (e.g. 768 or 1024) needs to match a fixed DB column
25
+ dimension (e.g. 1536), or returns `vec` unchanged when `target_dim` is None or matches.
26
+ """
27
+ if not target_dim or len(vec) == target_dim:
28
+ return vec
29
+ if len(vec) > target_dim:
30
+ sliced = vec[:target_dim]
31
+ norm = math.sqrt(sum(x * x for x in sliced)) or 1.0
32
+ return [x / norm for x in sliced]
33
+ return vec + [0.0] * (target_dim - len(vec))
34
+
35
+
36
+ def _extract_json_object(raw_text: str) -> str:
37
+ """Strips markdown code fences if an LLM wraps JSON output in ```json ... ```."""
38
+ cleaned = raw_text.strip()
39
+ if cleaned.startswith("```"):
40
+ cleaned = re.sub(r"^```(?:json)?\s*", "", cleaned)
41
+ cleaned = re.sub(r"\s*```$", "", cleaned)
42
+ return cleaned.strip()
43
+
44
+
45
+ # =============================================================================
46
+ # 1. Google Gemini / Vertex AI Adapters
47
+ # =============================================================================
48
+
49
+
50
+ class GeminiEmbeddingAdapter(EmbeddingAdapter):
51
+ """Google GenAI (Gemini) embedding adapter using `google-genai` SDK."""
52
+
53
+ def __init__(
54
+ self,
55
+ model: str = "text-embedding-004",
56
+ api_key: str | None = None,
57
+ output_dimensionality: int = 1536,
58
+ ):
59
+ self.model = model
60
+ self.api_key = api_key
61
+ self.output_dimensionality = output_dimensionality
62
+ self._client: Any = None
63
+
64
+ def _get_client(self):
65
+ if self._client is None:
66
+ from google import genai
67
+
68
+ self._client = (
69
+ genai.Client(api_key=self.api_key) if self.api_key else genai.Client()
70
+ )
71
+ return self._client
72
+
73
+ async def embed(self, text: str) -> list[float]:
74
+ client = self._get_client()
75
+ resp = await asyncio.to_thread(
76
+ client.models.embed_content,
77
+ model=self.model,
78
+ contents=text,
79
+ )
80
+ return _align_vector_dim(
81
+ list(resp.embeddings[0].values), self.output_dimensionality
82
+ )
83
+
84
+
85
+ class GeminiOntologyExtractorAdapter(OntologyExtractorAdapter):
86
+ """
87
+ Compiles the active app's `CompiledTBox` into a structured prompt & Pydantic response schema
88
+ for Google Gemini (`google-genai`), supporting the Two-Bucket extraction pattern.
89
+ """
90
+
91
+ def __init__(self, model: str = "gemini-2.5-flash", api_key: str | None = None):
92
+ self.model = model
93
+ self.api_key = api_key
94
+ self._client: Any = None
95
+
96
+ def _get_client(self):
97
+ if self._client is None:
98
+ from google import genai
99
+
100
+ self._client = (
101
+ genai.Client(api_key=self.api_key) if self.api_key else genai.Client()
102
+ )
103
+ return self._client
104
+
105
+ @staticmethod
106
+ def build_tbox_system_instruction(tbox: CompiledTBox) -> str:
107
+ allowed_classes = ", ".join(sorted(tbox.classes.keys()))
108
+ relation_lines = [
109
+ f"- {r.predicate}: domain={r.domain_class}, range={r.range_class}, functional={r.is_functional}"
110
+ for r in tbox.relations.values()
111
+ ]
112
+ relations_block = "\n".join(relation_lines)
113
+ return (
114
+ "You are an Ontology-Guided Knowledge Graph Extractor & Smart Memory Classifier.\n"
115
+ "1. First, evaluate if the transcript is purely ephemeral social chitchat, pleasantries, or terminal sign-offs "
116
+ "(e.g., 'Have a great weekend everyone, talk Monday!'). If so, set `is_ephemeral_chitchat=True` and return empty lists.\n"
117
+ "2. Pay close attention to conversational context: if an agent asks a question ('Did checkout-api fail over to us-west-2?') "
118
+ "and the user replies briefly ('Yes' or 'Confirmed'), treat that as a confirmed fact and extract it!\n"
119
+ "3. For each extracted entity and fact, assign `scope`:\n"
120
+ " - 'user_global' for personal user preferences, communication style, role, or timezone.\n"
121
+ " - 'domain_shared' for domain/system/customer facts conforming to the TBox.\n"
122
+ " - 'app_private' for app-specific workflow state or candidate concepts.\n"
123
+ f"ALLOWED TBOX CLASSES: [{allowed_classes}]\n"
124
+ f"ALLOWED TBOX RELATIONS:\n{relations_block}\n"
125
+ "If an important entity does not fit a specific domain class, classify it as 'p:CandidateConcept'."
126
+ )
127
+
128
+ async def extract(self, transcript: str, tbox: CompiledTBox) -> ExtractionPayload:
129
+ client = self._get_client()
130
+ from google.genai import types
131
+
132
+ sys_instruction = self.build_tbox_system_instruction(tbox)
133
+ resp = await asyncio.to_thread(
134
+ client.models.generate_content,
135
+ model=self.model,
136
+ contents=transcript,
137
+ config=types.GenerateContentConfig(
138
+ system_instruction=sys_instruction,
139
+ response_mime_type="application/json",
140
+ response_schema=ExtractionPayload,
141
+ temperature=0.0,
142
+ ),
143
+ )
144
+ if getattr(resp, "parsed", None) and isinstance(resp.parsed, ExtractionPayload):
145
+ return resp.parsed
146
+ return ExtractionPayload.model_validate_json(_extract_json_object(resp.text))
147
+
148
+
149
+ # =============================================================================
150
+ # 2. Amazon Bedrock Adapters (Titan / Cohere Embeddings + Claude / Nova Converse)
151
+ # =============================================================================
152
+
153
+
154
+ class BedrockEmbeddingAdapter(EmbeddingAdapter):
155
+ """
156
+ Enterprise Amazon Bedrock Embedding Adapter (`bedrock-runtime`) supporting:
157
+ - Amazon Titan Text Embeddings V2 (`amazon.titan-embed-text-v2:0`, native dims 256/512/1024)
158
+ - Amazon Titan Embeddings G1 (`amazon.titan-embed-text-v1`, native dim 1536)
159
+ - Cohere Embed v3 on Bedrock (`cohere.embed-english-v3` / `cohere.embed-multilingual-v3`)
160
+ Supports cross-account IAM AssumeRole via `aws_auth_provider` and optional
161
+ `target_dim` alignment (e.g. 1536) for fixed pgvector schemas.
162
+ """
163
+
164
+ def __init__(
165
+ self,
166
+ model_id: str = "amazon.titan-embed-text-v2:0",
167
+ region: str = "us-east-1",
168
+ dimensions: int = 1024,
169
+ target_dim: int | None = None,
170
+ normalize: bool = True,
171
+ aws_auth_provider: AwsIamDatabaseAuthProvider | None = None,
172
+ bedrock_client: Any = None,
173
+ ):
174
+ self.model_id = model_id
175
+ self.region = region
176
+ self.dimensions = dimensions
177
+ self.target_dim = target_dim
178
+ self.normalize = normalize
179
+ self.aws_auth_provider = aws_auth_provider
180
+ self._client = bedrock_client
181
+
182
+ def _get_client(self) -> Any:
183
+ if self._client is None:
184
+ import boto3
185
+
186
+ session = (
187
+ self.aws_auth_provider.get_boto3_session()
188
+ if self.aws_auth_provider is not None
189
+ else boto3.Session(region_name=self.region)
190
+ )
191
+ self._client = session.client("bedrock-runtime", region_name=self.region)
192
+ return self._client
193
+
194
+ def _invoke_sync(self, text: str) -> list[float]:
195
+ client = self._get_client()
196
+ if "cohere" in self.model_id.lower():
197
+ body = json.dumps(
198
+ {
199
+ "texts": [text],
200
+ "input_type": "search_document",
201
+ "truncate": "END",
202
+ }
203
+ )
204
+ elif "titan-embed-text-v2" in self.model_id.lower():
205
+ body = json.dumps(
206
+ {
207
+ "inputText": text,
208
+ "dimensions": self.dimensions,
209
+ "normalize": self.normalize,
210
+ }
211
+ )
212
+ else:
213
+ # amazon.titan-embed-text-v1 (1536 dims)
214
+ body = json.dumps({"inputText": text})
215
+
216
+ resp = client.invoke_model(
217
+ modelId=self.model_id,
218
+ body=body,
219
+ accept="application/json",
220
+ contentType="application/json",
221
+ )
222
+ raw_body = resp["body"].read()
223
+ data = json.loads(raw_body.decode("utf-8") if isinstance(raw_body, bytes) else raw_body)
224
+ if "embedding" in data:
225
+ vec = list(data["embedding"])
226
+ elif "embeddings" in data and data["embeddings"]:
227
+ vec = list(data["embeddings"][0])
228
+ else:
229
+ raise ValueError(f"Unexpected Bedrock embedding response format: {list(data.keys())}")
230
+ return _align_vector_dim(vec, self.target_dim)
231
+
232
+ async def embed(self, text: str) -> list[float]:
233
+ return await asyncio.to_thread(self._invoke_sync, text)
234
+
235
+
236
+ class BedrockOntologyExtractorAdapter(OntologyExtractorAdapter):
237
+ """
238
+ Enterprise Amazon Bedrock Ontology Extractor (`bedrock-runtime` Converse API).
239
+ Works seamlessly across:
240
+ - Anthropic Claude 3.5 / 3.7 / 4 Sonnet & Haiku (`us.anthropic.claude-3-5-sonnet-20241022-v2:0`)
241
+ - Amazon Nova Pro / Lite (`us.amazon.nova-pro-v1:0`, `us.amazon.nova-lite-v1:0`)
242
+ - Meta Llama 3.3 Instruct (`us.meta.llama3-3-70b-instruct-v1:0`)
243
+ Uses Bedrock `converse` tool-use structured output (`toolConfig`) with automatic
244
+ fallback to JSON text parsing.
245
+ """
246
+
247
+ def __init__(
248
+ self,
249
+ model_id: str = "us.anthropic.claude-3-5-sonnet-20241022-v2:0",
250
+ region: str = "us-east-1",
251
+ aws_auth_provider: AwsIamDatabaseAuthProvider | None = None,
252
+ bedrock_client: Any = None,
253
+ ):
254
+ self.model_id = model_id
255
+ self.region = region
256
+ self.aws_auth_provider = aws_auth_provider
257
+ self._client = bedrock_client
258
+
259
+ def _get_client(self) -> Any:
260
+ if self._client is None:
261
+ import boto3
262
+
263
+ session = (
264
+ self.aws_auth_provider.get_boto3_session()
265
+ if self.aws_auth_provider is not None
266
+ else boto3.Session(region_name=self.region)
267
+ )
268
+ self._client = session.client("bedrock-runtime", region_name=self.region)
269
+ return self._client
270
+
271
+ def _converse_sync(self, transcript: str, tbox: CompiledTBox) -> ExtractionPayload:
272
+ client = self._get_client()
273
+ sys_instruction = GeminiOntologyExtractorAdapter.build_tbox_system_instruction(tbox)
274
+ schema = ExtractionPayload.model_json_schema()
275
+
276
+ resp = client.converse(
277
+ modelId=self.model_id,
278
+ system=[{"text": sys_instruction}],
279
+ messages=[
280
+ {
281
+ "role": "user",
282
+ "content": [{"text": transcript}],
283
+ }
284
+ ],
285
+ inferenceConfig={"temperature": 0.0},
286
+ toolConfig={
287
+ "tools": [
288
+ {
289
+ "toolSpec": {
290
+ "name": "emit_extraction_payload",
291
+ "description": "Emit structured ontology entities and bi-temporal facts.",
292
+ "inputSchema": {"json": schema},
293
+ }
294
+ }
295
+ ],
296
+ "toolChoice": {"tool": {"name": "emit_extraction_payload"}},
297
+ },
298
+ )
299
+ content_blocks = (
300
+ resp.get("output", {}).get("message", {}).get("content", [])
301
+ )
302
+ for block in content_blocks:
303
+ if "toolUse" in block and "input" in block["toolUse"]:
304
+ return ExtractionPayload.model_validate(block["toolUse"]["input"])
305
+ if "text" in block and block["text"].strip():
306
+ return ExtractionPayload.model_validate_json(
307
+ _extract_json_object(block["text"])
308
+ )
309
+ return ExtractionPayload(entities=[], facts=[])
310
+
311
+ async def extract(self, transcript: str, tbox: CompiledTBox) -> ExtractionPayload:
312
+ return await asyncio.to_thread(self._converse_sync, transcript, tbox)
313
+
314
+
315
+ # =============================================================================
316
+ # 3. OpenAI / Azure OpenAI / vLLM / LiteLLM (OpenAI-Compatible HTTP) Adapters
317
+ # =============================================================================
318
+
319
+
320
+ class OpenAICompatibleEmbeddingAdapter(EmbeddingAdapter):
321
+ """
322
+ OpenAI-compatible Embedding Adapter supporting:
323
+ - OpenAI (`text-embedding-3-small`, `text-embedding-3-large` with native `dimensions=1536`)
324
+ - Azure OpenAI Service (with API key or `AzureEntraDatabaseAuthProvider` Bearer token)
325
+ - vLLM, LiteLLM Proxy, Together AI, Fireworks, or LM Studio (`/v1/embeddings`)
326
+ """
327
+
328
+ def __init__(
329
+ self,
330
+ model: str = "text-embedding-3-small",
331
+ api_key: str | None = None,
332
+ base_url: str = "https://api.openai.com/v1",
333
+ dimensions: int | None = 1536,
334
+ auth_provider: CloudAuthProvider | None = None,
335
+ http_client: httpx.AsyncClient | None = None,
336
+ ):
337
+ self.model = model
338
+ self.api_key = api_key or os.environ.get("OPENAI_API_KEY", "")
339
+ self.base_url = base_url.rstrip("/")
340
+ self.dimensions = dimensions
341
+ self.auth_provider = auth_provider
342
+ self._http = http_client
343
+
344
+ async def embed(self, text: str) -> list[float]:
345
+ token = (
346
+ await self.auth_provider.get_password()
347
+ if self.auth_provider is not None
348
+ else self.api_key
349
+ )
350
+ headers = {"Content-Type": "application/json"}
351
+ if token:
352
+ headers["Authorization"] = f"Bearer {token}"
353
+
354
+ payload: dict[str, Any] = {"model": self.model, "input": text}
355
+ if self.dimensions is not None and "text-embedding-3" in self.model:
356
+ payload["dimensions"] = self.dimensions
357
+
358
+ if self._http is not None:
359
+ resp = await self._http.post(
360
+ f"{self.base_url}/embeddings", headers=headers, json=payload
361
+ )
362
+ else:
363
+ async with httpx.AsyncClient(timeout=30.0) as client:
364
+ resp = await client.post(
365
+ f"{self.base_url}/embeddings", headers=headers, json=payload
366
+ )
367
+ resp.raise_for_status()
368
+ data = resp.json()
369
+ vec = list(data["data"][0]["embedding"])
370
+ return _align_vector_dim(vec, self.dimensions)
371
+
372
+
373
+ class OpenAICompatibleOntologyExtractorAdapter(OntologyExtractorAdapter):
374
+ """
375
+ OpenAI-compatible Ontology Extractor supporting OpenAI (`gpt-4o-mini`, `gpt-4o`),
376
+ Azure OpenAI, vLLM, LiteLLM, or DeepSeek (`/v1/chat/completions`).
377
+ """
378
+
379
+ def __init__(
380
+ self,
381
+ model: str = "gpt-4o-mini",
382
+ api_key: str | None = None,
383
+ base_url: str = "https://api.openai.com/v1",
384
+ auth_provider: CloudAuthProvider | None = None,
385
+ http_client: httpx.AsyncClient | None = None,
386
+ ):
387
+ self.model = model
388
+ self.api_key = api_key or os.environ.get("OPENAI_API_KEY", "")
389
+ self.base_url = base_url.rstrip("/")
390
+ self.auth_provider = auth_provider
391
+ self._http = http_client
392
+
393
+ async def extract(self, transcript: str, tbox: CompiledTBox) -> ExtractionPayload:
394
+ token = (
395
+ await self.auth_provider.get_password()
396
+ if self.auth_provider is not None
397
+ else self.api_key
398
+ )
399
+ headers = {"Content-Type": "application/json"}
400
+ if token:
401
+ headers["Authorization"] = f"Bearer {token}"
402
+
403
+ sys_instruction = (
404
+ GeminiOntologyExtractorAdapter.build_tbox_system_instruction(tbox)
405
+ + "\nRespond strictly with a JSON object matching fields: "
406
+ "`is_ephemeral_chitchat` (bool), `classification_reason` (str), "
407
+ "`entities` (list), `facts` (list)."
408
+ )
409
+ payload = {
410
+ "model": self.model,
411
+ "temperature": 0.0,
412
+ "response_format": {"type": "json_object"},
413
+ "messages": [
414
+ {"role": "system", "content": sys_instruction},
415
+ {"role": "user", "content": transcript},
416
+ ],
417
+ }
418
+ if self._http is not None:
419
+ resp = await self._http.post(
420
+ f"{self.base_url}/chat/completions", headers=headers, json=payload
421
+ )
422
+ else:
423
+ async with httpx.AsyncClient(timeout=45.0) as client:
424
+ resp = await client.post(
425
+ f"{self.base_url}/chat/completions", headers=headers, json=payload
426
+ )
427
+ resp.raise_for_status()
428
+ content = resp.json()["choices"][0]["message"]["content"]
429
+ return ExtractionPayload.model_validate_json(_extract_json_object(content))
430
+
431
+
432
+ # =============================================================================
433
+ # 4. Ollama Local Neural Adapters (Embeddings & Structured Extraction)
434
+ # =============================================================================
435
+
436
+
437
+ class OllamaEmbeddingAdapter(EmbeddingAdapter):
438
+ """
439
+ Local Ollama Embedding Adapter (`http://127.0.0.1:11434/api/embed`) for models such as:
440
+ - `nomic-embed-text` (768 dims)
441
+ - `mxbai-embed-large` (1024 dims)
442
+ - `bge-m3` (1024 dims)
443
+ - `all-minilm` (384 dims)
444
+ Supports optional `target_dim` alignment (e.g. `target_dim=1536`) so local models work
445
+ seamlessly against fixed 1536-dim PostgreSQL schemas without altering DDL.
446
+ """
447
+
448
+ def __init__(
449
+ self,
450
+ model: str = "nomic-embed-text",
451
+ base_url: str = "http://127.0.0.1:11434",
452
+ target_dim: int | None = None,
453
+ http_client: httpx.AsyncClient | None = None,
454
+ ):
455
+ self.model = model
456
+ self.base_url = base_url.rstrip("/")
457
+ self.target_dim = target_dim
458
+ self._http = http_client
459
+
460
+ async def embed(self, text: str) -> list[float]:
461
+ payload = {"model": self.model, "input": text}
462
+ if self._http is not None:
463
+ resp = await self._http.post(f"{self.base_url}/api/embed", json=payload)
464
+ else:
465
+ async with httpx.AsyncClient(timeout=30.0) as client:
466
+ resp = await client.post(f"{self.base_url}/api/embed", json=payload)
467
+ resp.raise_for_status()
468
+ data = resp.json()
469
+ vec = (
470
+ list(data["embeddings"][0])
471
+ if "embeddings" in data
472
+ else list(data["embedding"])
473
+ )
474
+ return _align_vector_dim(vec, self.target_dim)
475
+
476
+
477
+ class OllamaOntologyExtractorAdapter(OntologyExtractorAdapter):
478
+ """
479
+ Local Ollama Structured Ontology Extractor (`http://127.0.0.1:11434/api/chat`)
480
+ using Ollama's native JSON schema enforcement (`format=ExtractionPayload.model_json_schema()`)
481
+ for local open-weight models (`qwen2.5`, `llama3.2`, `mistral`, `gemma2`).
482
+ """
483
+
484
+ def __init__(
485
+ self,
486
+ model: str = "qwen2.5:7b",
487
+ base_url: str = "http://127.0.0.1:11434",
488
+ http_client: httpx.AsyncClient | None = None,
489
+ ):
490
+ self.model = model
491
+ self.base_url = base_url.rstrip("/")
492
+ self._http = http_client
493
+
494
+ async def extract(self, transcript: str, tbox: CompiledTBox) -> ExtractionPayload:
495
+ sys_instruction = GeminiOntologyExtractorAdapter.build_tbox_system_instruction(tbox)
496
+ payload = {
497
+ "model": self.model,
498
+ "stream": False,
499
+ "format": ExtractionPayload.model_json_schema(),
500
+ "options": {"temperature": 0.0},
501
+ "messages": [
502
+ {"role": "system", "content": sys_instruction},
503
+ {"role": "user", "content": transcript},
504
+ ],
505
+ }
506
+ if self._http is not None:
507
+ resp = await self._http.post(f"{self.base_url}/api/chat", json=payload)
508
+ else:
509
+ async with httpx.AsyncClient(timeout=60.0) as client:
510
+ resp = await client.post(f"{self.base_url}/api/chat", json=payload)
511
+ resp.raise_for_status()
512
+ content = resp.json()["message"]["content"]
513
+ return ExtractionPayload.model_validate_json(_extract_json_object(content))
514
+
515
+
516
+ # =============================================================================
517
+ # 5. Local Sentence-Transformers / FastEmbed In-Process Adapter
518
+ # =============================================================================
519
+
520
+
521
+ class LocalSentenceTransformerEmbeddingAdapter(EmbeddingAdapter):
522
+ """
523
+ In-process local neural embedding adapter supporting `sentence-transformers` or `fastembed`
524
+ (e.g., `BAAI/bge-small-en-v1.5`, `all-MiniLM-L6-v2`) with optional `target_dim` alignment.
525
+ """
526
+
527
+ def __init__(
528
+ self,
529
+ model_name: str = "BAAI/bge-small-en-v1.5",
530
+ target_dim: int | None = None,
531
+ ):
532
+ self.model_name = model_name
533
+ self.target_dim = target_dim
534
+ self._model: Any = None
535
+ self._backend: str = ""
536
+
537
+ def _encode_sync(self, text: str) -> list[float]:
538
+ if self._model is None:
539
+ try:
540
+ from sentence_transformers import SentenceTransformer # type: ignore
541
+
542
+ self._model = SentenceTransformer(self.model_name)
543
+ self._backend = "sentence_transformers"
544
+ except ImportError:
545
+ from fastembed import TextEmbedding # type: ignore
546
+
547
+ self._model = TextEmbedding(model_name=self.model_name)
548
+ self._backend = "fastembed"
549
+
550
+ if self._backend == "sentence_transformers":
551
+ vec = self._model.encode(text, normalize_embeddings=True).tolist()
552
+ else:
553
+ vec = list(next(self._model.embed([text])))
554
+ return _align_vector_dim([float(x) for x in vec], self.target_dim)
555
+
556
+ async def embed(self, text: str) -> list[float]:
557
+ return await asyncio.to_thread(self._encode_sync, text)
558
+
559
+
560
+ # =============================================================================
561
+ # 6. Deterministic Offline / CI Adapters
562
+ # =============================================================================
563
+
564
+
565
+ class DeterministicHashEmbeddingAdapter(EmbeddingAdapter):
566
+ """
567
+ Zero-dependency deterministic n-gram feature hashing embedder for local testing, CI/CD,
568
+ and offline development without API keys. Produces normalized unit vectors.
569
+ """
570
+
571
+ def __init__(self, dim: int = 64):
572
+ self.dim = dim
573
+
574
+ async def embed(self, text: str) -> list[float]:
575
+ vec = [0.0] * self.dim
576
+ tokens = [
577
+ t.strip(".,!?;:()[]\"'").lower()
578
+ for t in text.split()
579
+ if t.strip(".,!?;:()[]\"'")
580
+ ]
581
+ if not tokens:
582
+ vec[0] = 1.0
583
+ return vec
584
+ for tok in tokens:
585
+ h = int(hashlib.md5(tok.encode("utf-8")).hexdigest(), 16)
586
+ idx = h % self.dim
587
+ sign = 1.0 if ((h >> 8) & 1) == 0 else -1.0
588
+ vec[idx] += sign
589
+ norm = math.sqrt(sum(v * v for v in vec)) or 1.0
590
+ return [v / norm for v in vec]
591
+
592
+
593
+ class RuleBasedMockExtractorAdapter(OntologyExtractorAdapter):
594
+ """
595
+ Configurable mock extractor for unit tests and local simulations.
596
+ Allows registering scripted `ExtractionPayload` responses or using rule patterns.
597
+ """
598
+
599
+ def __init__(self):
600
+ self.queued_payloads: list[ExtractionPayload] = []
601
+ self.keyword_rules: list[tuple[str, ExtractionPayload]] = []
602
+
603
+ def enqueue(self, payload: ExtractionPayload) -> None:
604
+ self.queued_payloads.append(payload)
605
+
606
+ def add_keyword_rule(self, keyword: str, payload: ExtractionPayload) -> None:
607
+ self.keyword_rules.append((keyword.lower(), payload))
608
+
609
+ async def extract(self, transcript: str, tbox: CompiledTBox) -> ExtractionPayload:
610
+ if self.queued_payloads:
611
+ return self.queued_payloads.pop(0)
612
+ lower_t = transcript.lower()
613
+ for kw, payload in self.keyword_rules:
614
+ if kw in lower_t:
615
+ return payload
616
+ return ExtractionPayload(entities=[], facts=[])