enne2/pi-qmem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(hierarchy): supporto metadati strutturati e gerarchici su Qdrant (parent_id, level, topic, links)

Browse Source
This commit is contained in:
Matteo Benedetto
2026-08-23 13:07:16 +02:00
parent fc11f878f6
commit 369a2c2d9e
4 changed files with 224 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
extensions/index.ts
+68 -5
View File
@@ -207,6 +207,23 @@ export default function qmemExtension(pi: ExtensionAPI) {
),
supersedes_id: Type.Optional(Type.String({ description: "UUID del record da supersedere (correzione): il nuovo record diventa la versione attiva, il vecchio resta in archivio marcato superseded." })),
supersede_reason: Type.Optional(Type.String({ description: "Motivo della correzione (visibile in audit e sul vecchio record)." })),
parent_id: Type.Optional(Type.String({ description: "UUID del record genitore per organizzazione gerarchica/subtopic." })),
level: Type.Optional(
Type.Union([Type.Literal("L1_ROOT"), Type.Literal("L2_SUBTOPIC"), Type.Literal("L3_DETAIL")], {
description: "Livello gerarchico (L1_ROOT = indice macro-topic, L2_SUBTOPIC = dettaglio specialistico, L3_DETAIL).",
}),
),
topic: Type.Optional(Type.String({ description: "Topic ID gerarchico (es. ALFA-ROMEO-GT-1300-JUNIOR/SPECS)." })),
links: Type.Optional(
Type.Array(
Type.Object({
target_id: Type.String({ description: "UUID del record target collegato." }),
predicate: Type.Optional(Type.String({ description: "Tipo di relazione (parent_of, part_of, relates_to, supersedes...)." })),
weight: Type.Optional(Type.Number({ description: "Peso della relazione (default: 1.0)." })),
}),
{ description: "Collegamenti relazionali espliciti verso altri record." },
),
),
}),
async execute(toolCallId, params, signal, onUpdate, ctx) {
const cfg = loadConfig();
@@ -245,6 +262,10 @@ export default function qmemExtension(pi: ExtensionAPI) {
expires_at: p.expires_at,
supersedes_id: p.supersedes_id,
supersede_reason: p.supersede_reason,
parent_id: p.parent_id,
level: p.level,
topic: p.topic,
links: p.links,
},
signal,
idemKey,
@@ -261,9 +282,10 @@ export default function qmemExtension(pi: ExtensionAPI) {
dupes.map((d: any) => ` - ${d.memory_id} (score ${d.score}): ${String(d.text).slice(0, 100)}`).join("\n") +
"\nValuta se il nuovo record è davvero necessario o se conviene qmem_correct sul duplicato."
: "";
const extra = `${p.level ? `, level ${p.level}` : ""}${p.topic ? `, topic ${p.topic}` : ""}${p.parent_id ? ` — parent ${p.parent_id}` : ""}`;
return {
content: [{ type: "text", text: `Memoria salvata: ${data.memory_id} (${p.kind ?? "fact"}, scope ${p.scope ?? "agent"})${p.supersedes_id ? ` — supersede ${p.supersedes_id}` : ""}${dupWarning}` }],
details: { memory_id: data.memory_id, created_at: data.created_at, duplicates: dupes.length },
content: [{ type: "text", text: `Memoria salvata: ${data.memory_id} (${p.kind ?? "fact"}, scope ${p.scope ?? "agent"}${extra})${p.supersedes_id ? ` — supersede ${p.supersedes_id}` : ""}${dupWarning}` }],
details: { memory_id: data.memory_id, created_at: data.created_at, duplicates: dupes.length, parent_id: p.parent_id, level: p.level, topic: p.topic },
};
},
});
@@ -318,6 +340,13 @@ export default function qmemExtension(pi: ExtensionAPI) {
"non come similarità. min_score resta applicato al ramo vettoriale (anti-rumore).",
}),
),
parent_id: Type.Optional(Type.String({ description: "Filtra per UUID del record genitore." })),
level: Type.Optional(
Type.Union([Type.Literal("L1_ROOT"), Type.Literal("L2_SUBTOPIC"), Type.Literal("L3_DETAIL")], {
description: "Filtra per livello gerarchico.",
}),
),
topic: Type.Optional(Type.String({ description: "Filtra per topic esatto." })),
}),
async execute(toolCallId, params, signal, onUpdate, ctx) {
const cfg = loadConfig();
@@ -342,6 +371,9 @@ export default function qmemExtension(pi: ExtensionAPI) {
min_score: p.min_score ?? 0.45,
top_k: p.top_k ?? 5,
hybrid: p.hybrid ?? false,
parent_id: p.parent_id,
level: p.level,
topic: p.topic,
},
signal,
);
@@ -364,8 +396,13 @@ export default function qmemExtension(pi: ExtensionAPI) {
};
}
const lines = results.map(
(r: any, i: number) =>
`${i + 1}. [${r.kind}/${r.scope} score=${r.score}${r.score < 0.6 ? " ⚠️" : ""}${r.confidence ? ` conf=${r.confidence}` : ""}] ${r.text}\n (id: ${r.memory_id}, agente: ${r.agent_id ?? "?"}, creato: ${r.created_at ?? "?"}${r.source ? `, fonte: ${r.source}` : ""}${r.supersedes_id ? `, supersede ${r.supersedes_id}` : ""}${r.superseded_by ? `, ⚠️ superseduto da ${r.superseded_by}` : ""})`,
(r: any, i: number) => {
const lvl = r.level ? ` [${r.level}]` : "";
const top = r.topic ? ` (${r.topic})` : "";
const parent = r.parent_id ? `, parent: ${r.parent_id}` : "";
const links = r.links && r.links.length > 0 ? `, links: ${r.links.length}` : "";
return `${i + 1}. [${r.kind}/${r.scope}${lvl}${top} score=${r.score}${r.score < 0.6 ? " ⚠️" : ""}${r.confidence ? ` conf=${r.confidence}` : ""}] ${r.text}\n (id: ${r.memory_id}${parent}${links}, agente: ${r.agent_id ?? "?"}, creato: ${r.created_at ?? "?"}${r.source ? `, fonte: ${r.source}` : ""}${r.supersedes_id ? `, supersede ${r.supersedes_id}` : ""}${r.superseded_by ? `, ⚠️ superseduto da ${r.superseded_by}` : ""})`;
},
);
return {
content: [{ type: "text", text: lines.join("\n") }],
@@ -410,6 +447,23 @@ export default function qmemExtension(pi: ExtensionAPI) {
}),
),
agent_id: Type.Optional(Type.String({ description: "Nome dell'agente che corregge (solo provenienza)." })),
parent_id: Type.Optional(Type.String({ description: "UUID del record genitore (default: eredita dal record superseduto se presente)." })),
level: Type.Optional(
Type.Union([Type.Literal("L1_ROOT"), Type.Literal("L2_SUBTOPIC"), Type.Literal("L3_DETAIL")], {
description: "Livello gerarchico del nuovo record.",
}),
),
topic: Type.Optional(Type.String({ description: "Topic ID gerarchico del nuovo record." })),
links: Type.Optional(
Type.Array(
Type.Object({
target_id: Type.String(),
predicate: Type.Optional(Type.String()),
weight: Type.Optional(Type.Number()),
}),
{ description: "Collegamenti relazionali espliciti." },
),
),
}),
async execute(toolCallId, params, signal, onUpdate, ctx) {
const cfg = loadConfig();
@@ -496,6 +550,10 @@ export default function qmemExtension(pi: ExtensionAPI) {
source: "qmem_correct",
supersedes_id: memoryId,
supersede_reason: p.reason,
parent_id: p.parent_id ?? orig.parent_id,
level: p.level ?? orig.level,
topic: p.topic ?? orig.topic,
links: p.links ?? orig.links,
},
signal,
idemKey,
@@ -610,10 +668,12 @@ export default function qmemExtension(pi: ExtensionAPI) {
}
const r = data ?? {};
const meta = [
`[${r.kind ?? "?"}/${r.scope ?? "?"}${r.confidence ? ` conf=${r.confidence}` : ""}]`,
`[${r.kind ?? "?"}/${r.scope ?? "?"}${r.level ? ` ${r.level}` : ""}${r.topic ? ` (${r.topic})` : ""}${r.confidence ? ` conf=${r.confidence}` : ""}]`,
`project: ${r.project_id ?? "?"}`,
`agente: ${r.agent_id ?? "?"}, creato: ${r.created_at ?? "?"}${r.source ? `, fonte: ${r.source}` : ""}`,
];
if (r.parent_id) meta.push(`parent: ${r.parent_id}`);
if (r.links && r.links.length > 0) meta.push(`links: ${r.links.length}`);
if (r.supersedes_id) meta.push(`supersede ${r.supersedes_id}`);
if (r.superseded_by) meta.push(`⚠️ SUPERSEDUTO da ${r.superseded_by}`);
if (r.expires_at) meta.push(`scade: ${r.expires_at}`);
@@ -625,6 +685,9 @@ export default function qmemExtension(pi: ExtensionAPI) {
kind: r.kind,
scope: r.scope,
project_id: r.project_id,
parent_id: r.parent_id,
level: r.level,
topic: r.topic,
superseded_by: r.superseded_by ?? null,
},
};
gateway/main.py
+45 -5
View File
@@ -66,7 +66,7 @@ GUARDRAIL_VERSION = "similarity-v1"
# Versione del codice: hash del commit Git da cui è stato costruito il container
# (iniettato come build arg nel Dockerfile: ARG GIT_COMMIT / ENV GIT_COMMIT)
GIT_COMMIT = os.environ.get("GIT_COMMIT", "unknown").strip()
GATEWAY_VERSION = os.environ.get("GATEWAY_VERSION", "2.7.0").strip()
GATEWAY_VERSION = os.environ.get("GATEWAY_VERSION", "2.8.0").strip()
# Metriche: push a VictoriaMetrics (stesso pattern dell'energy engine domotics)
VM_PUSH_URL = os.environ.get("VM_PUSH_URL", "http://host.docker.internal:8428/api/v1/import/prometheus")
@@ -110,7 +110,7 @@ async def lifespan(_app: FastAPI):
SPARSE_VECTOR_NAME: qm.SparseVectorParams(modifier=qm.Modifier.IDF),
},
)
for field in ("agent_id", "project_id", "scope", "kind", "supersedes_id", "superseded_by", "text_hash"):
for field in ("agent_id", "project_id", "scope", "kind", "supersedes_id", "superseded_by", "text_hash", "parent_id", "level", "topic"):
qdrant.create_payload_index(
collection_name=COLLECTION,
field_name=field,
@@ -124,6 +124,16 @@ async def lifespan(_app: FastAPI):
log.info("collection %s creata con indici (dense + sparse %s)", COLLECTION, SPARSE_VECTOR_NAME)
else:
log.info("collection %s già esistente", COLLECTION)
# Migrazione indici gerarchici: crea se mancanti
for field in ("parent_id", "level", "topic"):
try:
qdrant.create_payload_index(
collection_name=COLLECTION,
field_name=field,
field_schema=qm.PayloadSchemaType.KEYWORD,
)
except Exception: # noqa: BLE001
pass
# Migrazione: aggiunge lo sparse vector se manca (collection pre-ibrida)
info = qdrant.get_collection(COLLECTION)
sparse_vectors = (info.config.params.sparse_vectors or {}) if info.config and info.config.params else {}
@@ -158,7 +168,7 @@ async def lifespan(_app: FastAPI):
_http = None
app = FastAPI(title="Memory Gateway", version="2.7.0", lifespan=lifespan)
app = FastAPI(title="Memory Gateway", version="2.8.0", lifespan=lifespan)
qdrant = QdrantClient(url=QDRANT_URL, api_key=QDRANT_API_KEY)
# Request ID: generato per richiesta, loggato nell'audit e restituito in header
@@ -226,6 +236,12 @@ def _invalidate_meta() -> None:
# ---------------------------------------------------------------------------
# Modelli
# ---------------------------------------------------------------------------
class MemoryLink(BaseModel):
target_id: str = Field(..., description="UUID del record target collegato")
predicate: str = Field(default="part_of", max_length=64, description="Tipo di relazione: parent_of, part_of, relates_to, supersedes...")
weight: float = Field(default=1.0, ge=0.0, le=1.0)
class MemoryIn(BaseModel):
text: str = Field(min_length=1, max_length=MAX_TEXT_LEN)
kind: Literal["decision", "fact", "episode", "preference"] = "fact"
@@ -237,6 +253,10 @@ class MemoryIn(BaseModel):
expires_at: Optional[str] = None # ISO 8601
supersedes_id: Optional[str] = None
supersede_reason: Optional[str] = Field(default=None, max_length=512)
parent_id: Optional[str] = Field(default=None, description="UUID del record genitore per gerarchia/subtopic")
level: Optional[Literal["L1_ROOT", "L2_SUBTOPIC", "L3_DETAIL"]] = Field(default=None, description="Livello gerarchico del record")
topic: Optional[str] = Field(default=None, max_length=128, description="Topic gerarchico (es. ALFA-ROMEO-GT-1300-JUNIOR/SPECS)")
links: Optional[list[MemoryLink]] = Field(default=None, description="Collegamenti semantici e relazionali verso altri record")
@field_validator("expires_at")
@classmethod
@@ -260,6 +280,9 @@ class SearchIn(BaseModel):
min_score: Optional[float] = Field(default=None, ge=0.0, le=1.0)
top_k: int = Field(default=5, ge=1, le=20)
hybrid: bool = Field(default=False, description="True = hybrid retrieval (BM25 + vettoriale, RRF). I punteggi risultanti sono RRF, non cosine.")
parent_id: Optional[str] = Field(default=None, description="Filtra per UUID del record genitore")
level: Optional[Literal["L1_ROOT", "L2_SUBTOPIC", "L3_DETAIL"]] = Field(default=None, description="Filtra per livello gerarchico")
topic: Optional[str] = Field(default=None, description="Filtra per topic esatto")
# ---------------------------------------------------------------------------
@@ -334,7 +357,7 @@ def _find_similar(text: str, vector: list[float], top_k: int = 3) -> list[dict]:
]
def _decide_guardrail(text: str, vector: list[float]) -> dict:
def _decide_guardrail(text: str, vector: list[float], topic: Optional[str] = None, parent_id: Optional[str] = None) -> dict:
"""Applica il guardrail a 2 strati. Ritorna {decision, reason, matches}."""
# Strato 1 — hash esatto (duplicato identico)
text_hash = _text_hash(text)
@@ -365,6 +388,9 @@ def _decide_guardrail(text: str, vector: list[float]) -> dict:
top1 = matches[0]["score"]
if top1 >= GUARDRAIL_BLOCK_THRESHOLD:
# Se il nuovo record ha un topic o parent_id esplicito che lo differenzia, permetti con WARN
if (topic or parent_id) and any(m.get("memory_id") != parent_id for m in matches):
return {"decision": "WARN", "reason": "HIERARCHICAL_SUBTOPIC", "matches": matches}
return {"decision": "BLOCK", "reason": "KNOWN_SOLUTION", "matches": matches}
if top1 >= GUARDRAIL_WARN_THRESHOLD:
return {"decision": "WARN", "reason": "MODERATE_SIMILARITY", "matches": matches}
@@ -512,7 +538,7 @@ async def add_memory(
# Il supersede esplicito è una correzione intenzionale: bypassa il guardrail.
guardrail: Optional[dict] = None
if GUARDRAIL_ENABLED and not body.supersedes_id:
guardrail = _decide_guardrail(body.text, vector)
guardrail = _decide_guardrail(body.text, vector, topic=body.topic, parent_id=body.parent_id)
if guardrail["decision"] == "BLOCK":
_audit(
key,
@@ -544,6 +570,10 @@ async def add_memory(
"expires_at": _parse_ts(body.expires_at),
"supersedes_id": superseded_id,
"supersede_reason": body.supersede_reason,
"parent_id": body.parent_id,
"level": body.level,
"topic": body.topic,
"links": [link.model_dump() for link in body.links] if body.links else None,
"embedding_model": EMBED_MODEL,
"text_hash": _text_hash(body.text),
}
@@ -600,6 +630,12 @@ async def search_memories(body: SearchIn, key: str = Depends(require_auth)) -> d
must.append(qm.FieldCondition(key="project_id", match=qm.MatchValue(value=body.project_id)))
if body.scope:
must.append(qm.FieldCondition(key="scope", match=qm.MatchValue(value=body.scope)))
if body.parent_id:
must.append(qm.FieldCondition(key="parent_id", match=qm.MatchValue(value=body.parent_id)))
if body.level:
must.append(qm.FieldCondition(key="level", match=qm.MatchValue(value=body.level)))
if body.topic:
must.append(qm.FieldCondition(key="topic", match=qm.MatchValue(value=body.topic)))
if not body.include_superseded:
# default: esclude i record già corretti (superseded_by presente)
must.append(qm.IsEmptyCondition(is_empty=qm.PayloadField(key="superseded_by")))
@@ -655,6 +691,10 @@ async def search_memories(body: SearchIn, key: str = Depends(require_auth)) -> d
"supersedes_id": h.payload.get("supersedes_id"),
"superseded_by": h.payload.get("superseded_by"),
"supersede_reason": h.payload.get("supersede_reason"),
"parent_id": h.payload.get("parent_id"),
"level": h.payload.get("level"),
"topic": h.payload.get("topic"),
"links": h.payload.get("links"),
}
for h in hits
]
gateway/tests/test_api.py
+94
View File
@@ -216,3 +216,97 @@ def test_status_espone_git_commit(client):
assert "git_commit" in data
assert "version" in data
assert "guardrail_version" in data
# ---------------------------------------------------------------------------
# Struttura Gerarchica e Relazionale
# ---------------------------------------------------------------------------
def test_create_and_retrieve_hierarchical_record(client):
"""Crea un nodo Root L1 e un nodo Figlio L2 con links, parent_id, level, topic."""
# 1. Crea Root L1
r_root = client.post(
"/v1/memories",
json=make_record(
text="Master Topic Alfa Romeo",
level="L1_ROOT",
topic="ALFA-ROMEO/ROOT",
),
headers=auth_headers(),
)
assert r_root.status_code == 200
root_id = r_root.json()["memory_id"]
# 2. Crea Figlio L2 collegato
r_child = client.post(
"/v1/memories",
json=make_record(
text="Scheda Tecnica Bialbero 1.3",
parent_id=root_id,
level="L2_SUBTOPIC",
topic="ALFA-ROMEO/SPECS",
links=[{"target_id": root_id, "predicate": "part_of", "weight": 1.0}],
),
headers=auth_headers(),
)
assert r_child.status_code == 200
child_id = r_child.json()["memory_id"]
# 3. Recupera e verifica payload strutturato
g = client.get(f"/v1/memories/{child_id}", headers=auth_headers())
assert g.status_code == 200
data = g.json()
assert data["parent_id"] == root_id
assert data["level"] == "L2_SUBTOPIC"
assert data["topic"] == "ALFA-ROMEO/SPECS"
assert len(data["links"]) == 1
assert data["links"][0]["target_id"] == root_id
def test_search_filters_hierarchical(client):
"""Filtra per parent_id, level e topic."""
r_root = client.post(
"/v1/memories",
json=make_record(text="Root doc", level="L1_ROOT", topic="TOPIC/ROOT"),
headers=auth_headers(),
)
root_id = r_root.json()["memory_id"]
client.post(
"/v1/memories",
json=make_record(text="Child A", parent_id=root_id, level="L2_SUBTOPIC", topic="TOPIC/A"),
headers=auth_headers(),
)
client.post(
"/v1/memories",
json=make_record(text="Child B", parent_id=root_id, level="L2_SUBTOPIC", topic="TOPIC/B"),
headers=auth_headers(),
)
# Cerca solo L1_ROOT
s1 = client.post(
"/v1/memories:search",
json={"query": "doc", "level": "L1_ROOT", "top_k": 5, "min_score": 0.0},
headers=auth_headers(),
)
assert s1.status_code == 200
assert len(s1.json()["results"]) == 1
assert s1.json()["results"][0]["level"] == "L1_ROOT"
# Cerca per parent_id
s2 = client.post(
"/v1/memories:search",
json={"query": "Child", "parent_id": root_id, "top_k": 5, "min_score": 0.0},
headers=auth_headers(),
)
assert s2.status_code == 200
assert len(s2.json()["results"]) == 2
# Cerca per topic specifico
s3 = client.post(
"/v1/memories:search",
json={"query": "Child", "topic": "TOPIC/A", "top_k": 5, "min_score": 0.0},
headers=auth_headers(),
)
assert s3.status_code == 200
assert len(s3.json()["results"]) == 1
assert s3.json()["results"][0]["topic"] == "TOPIC/A"
skills/qmem/SKILL.md
+17 -2
View File
@@ -11,10 +11,25 @@ Stack: estensione pi-qmem → gateway FastAPI (qmem.enne2.net) → Qdrant 1.19 +
| Tool | Uso |
|---|---|
| `qmem_search` | Ricerca semantica con filtri (kind, project_id, scope, top_k, include_superseded, min_score) |
| `qmem_store` | Salva un record (kind, project_id OBBLIGATORIO, scope, source, expires_at, supersedes_id) |
| `qmem_search` | Ricerca semantica con filtri (kind, project_id, scope, top_k, include_superseded, min_score, parent_id, level, topic) |
| `qmem_store` | Salva un record (kind, project_id OBBLIGATORIO, scope, source, expires_at, supersedes_id, parent_id, level, topic, links) |
| `qmem_correct` | Corregge una memoria falsa: nuovo record che supersede il vecchio |
| `qmem_meta` | Discovery: scope×kind, progetti, agenti, superseduti (per scegliere i filtri) |
| `qmem_get` | Recupero deterministico per UUID O(1) |
## Struttura Gerarchica e Relazioni (L1 Root + L2 Subtopics)
Quando si organizza un corpus di conoscenza strutturato o un dominio complesso:
1. **Nodi Foglia L2 (Dettaglio Specialistico):**
* Salva prima i record specifici di dettaglio con `level="L2_SUBTOPIC"`, `topic="MACRO-TOPIC/SUBTOPIC"` e `parent_id` (se già noto o collegabile).
* Esempio: `qmem_store(text="...", project_id="...", level="L2_SUBTOPIC", topic="ALFA-ROMEO-GT-1300/SPECS")`.
2. **Nodo Radice L1 (Master Topic Index):**
* Salva il record indice macro con `level="L1_ROOT"`, `topic="MACRO-TOPIC/ROOT"` e `links=[{"target_id": "<uuid-l2>", "predicate": "parent_of"}]`.
3. **Filtro nelle Ricerche:**
* Puoi filtrare in `qmem_search` per `parent_id="<uuid>"`, `level="L1_ROOT"`, oppure `topic="MACRO/SUB"`.
4. **Navigazione Deterministica:**
* Se atterri su un nodo L2, usa `parent_id` restituito nel payload per recuperare il Root con `qmem_get(memory_id)`.
## Punteggi di ricerca (BGE-M3, cosine)