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.
- agentic_composite_memory/__init__.py +2 -0
- agentic_composite_memory/py.typed +0 -0
- agentic_composite_memory-0.1.0.dist-info/METADATA +167 -0
- agentic_composite_memory-0.1.0.dist-info/RECORD +31 -0
- agentic_composite_memory-0.1.0.dist-info/WHEEL +4 -0
- agentic_composite_memory-0.1.0.dist-info/entry_points.txt +2 -0
- agentic_composite_memory-0.1.0.dist-info/licenses/LICENSE +17 -0
- agentic_memory_sdk/__init__.py +163 -0
- agentic_memory_sdk/adapters/__init__.py +33 -0
- agentic_memory_sdk/adapters/in_memory.py +439 -0
- agentic_memory_sdk/adapters/neo4j_cypher.py +65 -0
- agentic_memory_sdk/adapters/neptune_cypher.py +309 -0
- agentic_memory_sdk/adapters/opensearch_seed.py +322 -0
- agentic_memory_sdk/adapters/postgres_pgvector.py +484 -0
- agentic_memory_sdk/adapters/postgres_unified.py +511 -0
- agentic_memory_sdk/adapters/redis_playbook.py +157 -0
- agentic_memory_sdk/adapters/redis_unified.py +490 -0
- agentic_memory_sdk/adk_integration.py +250 -0
- agentic_memory_sdk/auth.py +380 -0
- agentic_memory_sdk/cli.py +137 -0
- agentic_memory_sdk/governance.py +713 -0
- agentic_memory_sdk/llm_extractors.py +616 -0
- agentic_memory_sdk/models.py +443 -0
- agentic_memory_sdk/ontology_loader.py +189 -0
- agentic_memory_sdk/ports.py +159 -0
- agentic_memory_sdk/py.typed +0 -0
- agentic_memory_sdk/server/__init__.py +4 -0
- agentic_memory_sdk/server/api.py +328 -0
- agentic_memory_sdk/server/main.py +384 -0
- agentic_memory_sdk/server/mcp_server.py +198 -0
- agentic_memory_sdk/service.py +1214 -0
|
@@ -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=[])
|