mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

refactor(memory): own solved-question lifecycle (#24)

Browse Source
This commit is contained in:
marcopan
2026-08-24 01:23:39 +02:00
parent 93fe0d733b
commit 4a654de84a
13 changed files with 511 additions and 201 deletions
Download Patch File Download Diff File Expand all files Collapse all files
harness/tht/cli/memory_cmd.py
+12 -17
View File
@@ -403,12 +403,12 @@ def index_solved_session(cfg, session_id: str) -> int:
from tht.adapters.factory import build_vector_store
from tht.cli.sql_cmd import promoted_tables_for
from tht.cli.vector_cmd import make_embedder
from tht.solved import build_solved_snapshot, save_solved_question
from tht.memory import index_solved_question
store = build_vector_store(cfg, require_write=True)
record = build_solved_snapshot(load_snapshot_or_exit(cfg, session_id), promoted_tables_for(cfg, session_id))
return save_solved_question(
record,
return index_solved_question(
load_snapshot_or_exit(cfg, session_id),
promoted_tables_for(cfg, session_id),
store=store,
embedder=make_embedder(cfg.embeddings),
)
@@ -423,7 +423,7 @@ def solved_index_cmd(
"""Indicizza la coppia domanda->SQL nel semantic store (backfill; il finalize lo fa da solo)."""
import json as _json
from tht.solved import SolvedIndexError
from tht.memory import SolvedIndexError
cfg = _load_config_or_exit(config)
require_vector_write_allowed(cfg, "memory solved-index")
@@ -460,7 +460,7 @@ def solved_search_cmd(
from tht.cli.vector_cmd import make_embedder, open_searcher
from tht.ports.vector import VectorReadUnavailable, VectorStoreError
from tht.solved import SOLVED_KIND
from tht.memory import search_solved_questions
from tht.vectorstore.embeddings import EmbeddingsError
cfg = _load_config_or_exit(config)
@@ -471,7 +471,12 @@ def solved_search_cmd(
try:
searcher = open_searcher(cfg)
embedder = make_embedder(cfg.embeddings)
hits = searcher.search(embedder.embed_query(question), top_n=top, kinds=[SOLVED_KIND])
results = search_solved_questions(
question,
searcher=searcher,
embedder=embedder,
top=top,
)
except (VectorStoreError, VectorReadUnavailable, EmbeddingsError, OperationalError) as e:
typer.secho(
f"ATTENZIONE: exemplar non disponibili ({e}). Prosegui senza.",
@@ -480,16 +485,6 @@ def solved_search_cmd(
if json_out:
typer.echo("[]")
return
results = [
{
"session_id": h.metadata.get("session_id", h.ref),
"question": h.metadata.get("question", h.content),
"sql": h.metadata.get("sql", ""),
"tables": h.metadata.get("tables", []),
"score": round(h.similarity, 4),
}
for h in hits
]
if json_out:
typer.echo(json.dumps(results, ensure_ascii=False, indent=2))
return
harness/tht/cli/search_cmd.py
+1 -1
View File
@@ -257,7 +257,7 @@ def pack_cmd(
from tht.cli.vector_cmd import make_embedder, open_searcher, require_vector_cfg
from tht.ports.vector import VectorReadUnavailable, VectorStoreError
from tht.search import combined_search, schema_tables
from tht.solved import SOLVED_KIND
from tht.memory import SOLVED_KIND
from tht.vectorstore.embeddings import EmbeddingsError
cfg = _load_config_or_exit(config)
harness/tht/cli/session_cmd.py
+23 -7
View File
@@ -578,10 +578,11 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
# --- batteria di validazione su sql_final.sql ---
assert sql is not None
promoted_tables = promoted_tables_for(cfg, session_id)
check = validate_sql(
sql,
physical=_load_physical_or_exit(cfg),
promoted_tables=promoted_tables_for(cfg, session_id),
promoted_tables=promoted_tables,
forbidden_functions=set(cfg.execution.forbidden_functions),
)
if not check.ok:
@@ -623,14 +624,29 @@ def finalize_cmd(session_id: str = typer.Argument(...), config: Path = CONFIG_OP
repository, session_id, validation_report=report, evidence=evidence
)
# --- memoria attiva (parte B): indicizza la coppia domanda->SQL, best-effort ---
# Import lazy: memory_cmd importa da session_cmd (un import top-level qui sarebbe
# circolare). Qualunque errore (writer key assente, VPN giu', Ollama spento) NON
# deve bloccare il finalize: l'indice e' derivato e recuperabile con
# `tht memory solved-index <id>`.
# Qualunque errore (writer key assente, VPN giu', Ollama spento) NON deve
# bloccare il finalize: l'indice e' derivato e recuperabile con
# `tht memory solved-index <id>`. Memory owns this best-effort policy; core
# has already committed the authoritative finalized snapshot above.
try:
from tht.cli.memory_cmd import index_solved_session
from tht.adapters.factory import build_vector_store
from tht.cli.vector_cmd import make_embedder
from tht.memory import index_solved_question_best_effort
if index_solved_session(cfg, session_id):
finalized_snapshot = repository.get(session_id)
outcome = index_solved_question_best_effort(
finalized_snapshot,
promoted_tables,
store_factory=lambda: build_vector_store(cfg, require_write=True),
embedder_factory=lambda: make_embedder(cfg.embeddings),
)
if outcome.error is not None:
typer.secho(
f"ATTENZIONE: coppia domanda->SQL non indicizzata ({outcome.error}). "
f"Recupera con `tht memory solved-index {session_id}`.",
fg=typer.colors.YELLOW, err=True,
)
elif outcome.upserted:
typer.secho(
"OK: coppia domanda->SQL indicizzata nel vectordb (solved_question).",
fg=typer.colors.GREEN,
harness/tht/memory/__init__.py
+63
View File
@@ -0,0 +1,63 @@
"""Public Memory facade for reusable decisions and solved-question exemplars."""
from .core import (
EDITABLE_FIELDS,
MAX_PROMOTION_CANDIDATES,
REUSABLE_TYPES,
MemoryNotFound,
MemoryRecord,
decided_memory_ids,
declined_promotion_seqs,
delete_record,
load_registry,
memory_vector_record_for_decision,
memory_vector_records,
preview_promotions,
preview_promotions_snapshot,
promote,
promote_snapshot,
recall_memories,
reusable_promotions,
reusable_promotions_snapshot,
save_one_memory,
save_registry,
update_record,
)
from .solved import (
SOLVED_KIND,
SolvedIndexError,
SolvedIndexOutcome,
index_solved_question,
index_solved_question_best_effort,
search_solved_questions,
)
__all__ = [
"EDITABLE_FIELDS",
"MAX_PROMOTION_CANDIDATES",
"REUSABLE_TYPES",
"SOLVED_KIND",
"MemoryNotFound",
"MemoryRecord",
"SolvedIndexError",
"SolvedIndexOutcome",
"decided_memory_ids",
"declined_promotion_seqs",
"delete_record",
"index_solved_question",
"index_solved_question_best_effort",
"load_registry",
"memory_vector_record_for_decision",
"memory_vector_records",
"preview_promotions",
"preview_promotions_snapshot",
"promote",
"promote_snapshot",
"recall_memories",
"reusable_promotions",
"reusable_promotions_snapshot",
"save_one_memory",
"save_registry",
"search_solved_questions",
"update_record",
]
harness/tht/memory.py → harness/tht/memory/core.py
View File
harness/tht/solved.py → harness/tht/memory/solved.py
+76 -33
View File
@@ -6,18 +6,26 @@ nel semantic store workspace-scoped, nel gruppo logico `memory` con kind dedicat
consulta nelle fasi F4/F6/F7 con `tht memory solved-search` come materiale di
riferimento (exemplar), NON come decisione da ri-applicare.
Scrittura: SOLO upsert one-row stile D11 (`save_solved_question`). Questi record
Scrittura: SOLO upsert one-row stile D11 (`index_solved_question`). Questi record
non passano MAI da `VectorStore.sync`/`RestVectorWriter.sync`: il passo
delete-stale del sync, ricevendo il solo record corrente, cancellerebbe le coppie
delle altre sessioni. Per lo stesso motivo l'hash di dedup e' calcolato qui
(domanda+SQL) e non dal solo content come fa il sync.
"""
from dataclasses import dataclass
from tht.phase import effective_decisions
from tht.ports.vector import VectorWriteRecord
from tht.session.models import SessionSnapshot
from tht.vectorstore.records import VectorRecord
from tht.vectorstore.store import content_hash
from .core import question_context
SOLVED_KIND = "solved_question"
def solved_question_record(
def _solved_question_record(
*, session_id: str, question: str, sql: str, tables: list[str]
) -> VectorRecord:
return VectorRecord(
@@ -38,18 +46,14 @@ def solved_question_record(
def _solved_hash(record: VectorRecord) -> str:
# La domanda e' l'embedding (content); l'SQL vive solo nel metadata. L'hash
# copre entrambi: un re-finalize che cambia solo l'SQL aggiorna la riga.
from tht.vectorstore.store import content_hash
return content_hash(record.content + "\n" + str(record.metadata.get("sql", "")))
def save_solved_question(record: VectorRecord, *, store, embedder) -> int:
def _save_solved_question(record: VectorRecord, *, store, embedder) -> int:
"""Upsert one-row della coppia domanda->SQL via writer key (stesso pattern di
save_one_memory, spec D11): hash dedup client-side, embedding solo se domanda
o SQL sono cambiati. Ritorna il
numero di righe upsertate (0 = invariata)."""
from tht.ports.vector import VectorWriteRecord
new_hash = _solved_hash(record)
existing = store.existing_hashes("memory", [SOLVED_KIND])
if existing.get(record.id) == new_hash:
@@ -65,39 +69,78 @@ class SolvedIndexError(Exception):
"""La sessione non ha (ancora) gli artefatti per il record solved_question."""
def build_solved_record(session_dir, manifest, promoted_tables) -> VectorRecord:
"""Costruisce il record dagli artefatti persistiti (vista effective D15):
richiede sql_final.sql e la decisione sql_approved; la domanda e' l'ultima
question_rewritten, fallback la domanda del manifest."""
from tht.memory import question_context
from tht.phase import effective_decisions
sql_file = session_dir / "sql_final.sql"
if not sql_file.exists():
raise SolvedIndexError("sql_final.sql assente")
decisions = effective_decisions(session_dir)
if not any(d.type == "sql_approved" for d in decisions):
raise SolvedIndexError("decisione sql_approved assente")
return solved_question_record(
session_id=manifest.id,
question=question_context(decisions, manifest),
sql=sql_file.read_text().strip(),
tables=sorted(promoted_tables or set()),
)
def build_solved_snapshot(snapshot, promoted_tables) -> VectorRecord:
from tht.memory import question_context
from tht.phase import effective_decisions
def _build_solved_snapshot(
snapshot: SessionSnapshot,
promoted_tables: set[str] | None,
) -> VectorRecord:
sql = snapshot.artifacts.get("sql_final")
if sql is None:
raise SolvedIndexError("sql_final.sql assente")
decisions = effective_decisions(snapshot)
if not any(d.type == "sql_approved" for d in decisions):
raise SolvedIndexError("decisione sql_approved assente")
return solved_question_record(
return _solved_question_record(
session_id=snapshot.manifest.id,
question=question_context(decisions, snapshot.manifest),
sql=sql.strip(), tables=sorted(promoted_tables or set()),
)
def index_solved_question(
snapshot: SessionSnapshot,
promoted_tables: set[str] | None,
*,
store,
embedder,
) -> int:
"""Index the finalized question through Memory's one-row, idempotent policy."""
return _save_solved_question(
_build_solved_snapshot(snapshot, promoted_tables),
store=store,
embedder=embedder,
)
@dataclass(frozen=True)
class SolvedIndexOutcome:
upserted: int | None
error: str | None = None
def index_solved_question_best_effort(
snapshot: SessionSnapshot,
promoted_tables: set[str] | None,
*,
store_factory,
embedder_factory,
) -> SolvedIndexOutcome:
"""Attempt derived indexing without turning it into workflow success state."""
try:
upserted = index_solved_question(
snapshot,
promoted_tables,
store=store_factory(),
embedder=embedder_factory(),
)
except Exception as error:
return SolvedIndexOutcome(upserted=None, error=str(error))
return SolvedIndexOutcome(upserted=upserted)
def search_solved_questions(question: str, *, searcher, embedder, top: int = 3) -> list[dict]:
"""Return solved-question exemplars in semantic-search rank order."""
hits = searcher.search(
embedder.embed_query(question),
top_n=top,
kinds=[SOLVED_KIND],
)
return [
{
"session_id": hit.metadata.get("session_id", hit.ref),
"question": hit.metadata.get("question", hit.content),
"sql": hit.metadata.get("sql", ""),
"tables": hit.metadata.get("tables", []),
"score": round(hit.similarity, 4),
}
for hit in hits
]