$ja1dZddlmZmZddlmZddlmZddlm Z ddl m Z ddl m Z eGd d ZGd d eZd S)u:Abstract base class for backend-specific data access operations. SQLDialect handles SQL *fragment* generation (param placeholders, JSON ops, vector distance, etc.) — stateless, no I/O. DataAccessOps handles multi-statement *execution* patterns that differ between backends (unnest batch insert vs executemany, LATERAL fan-out vs per-row query, DISTINCT ON vs GROUP BY workarounds, etc.). Methods receive a DatabaseConnection and execute complete operations. This eliminates scattered ``if backend_type == "postgresql"`` conditionals from business logic. Adding a new backend (e.g. Neon, Databricks) means implementing this ABC — consumer code never checks the backend directly. Follows the Strategy pattern (Fowler's "Replace Conditional with Polymorphism") and mirrors Django's ``DatabaseOperations`` architecture. )ABCabstractmethod) dataclass)Any)UUID)DatabaseConnection) ResultRowc<eZdZUdZeed<eed<eed<eed<dS)TagListingPartsz9Backend-specific SQL fragments for the tag listing query. tag_sourcenon_empty_checktag_col bank_prefixN)__name__ __module__ __qualname____doc__str__annotations__c/home/rurouni/.hermes/hermes-agent/venv/lib/python3.11/site-packages/hindsight_api/engine/db/ops.pyr r sBCCOOO LLLrr c'eZdZdZedefdZedede de e de e de e d e e d e e d e e dd fd Z e dbdede de e de e de de de de de e de e de e de de de e de de de de e f$dZ e dcdede de ede d e d!e d"e dd fd#Zedede de d$e e d%e dee e ff d&Zedede de d'e e de ef d(Zedede d)e d*e dd f d+Zeded,e d-e ed.e de ef d/Zeded0e d)e e de efd1Ze ddded0e de d3e d4e d5e d6e d7e de efd8Zed0e d,e d9e de fd:Zed;e d0e de fd<Zeded0e d,e d;e d=e d>e d9e dee ee ee effd?Zed0e defd@Zedede de dAe dBe dee e fdd fdCZededDe dAe dee e fdd f dEZede fdFZ edede dGe!de dHe dIe d zdJe e dKedLe ded zfdMZ"edede de de efdNZ#ededOe de de efdPZ$edede dGe!de dQe e dRe e!ded zfdSZ%edede dGe!de def dTZ&ededUe dGe de dVe dWe d zde efdXZ'ededUe dYe!de dZe d[e!dd fd\Z(edede d]e d^ee e fd_e de ef d`Z)de fdaZ*d S)e DataAccessOpszBackend-specific multi-statement data access operations. Each method encapsulates a complete DB operation that differs in execution strategy between backends. returncdS)zWhether this backend uses the observation_sources junction table. PG uses native array ops (source_memory_ids column) for reads and skips junction table writes. Oracle uses the junction table for both. Trselfs ruses_observation_sources_tablez,DataAccessOps.uses_observation_sources_table-s trconntable chunk_ids document_idsbank_ids chunk_texts chunk_indicescontent_hashesNc  KdS)zBulk upsert chunks with ON CONFLICT handling. PG uses INSERT ... SELECT FROM unnest() with ON CONFLICT DO UPDATE. Non-PG uses bulk_insert_from_arrays (executemany). Nr) rr!r"r#r$r%r&r'r(s rbulk_upsert_chunksz DataAccessOps.bulk_upsert_chunks8 " rnativebank_id fact_texts embeddings event_datesoccurred_starts occurred_ends mentioned_atscontexts fact_typesmetadata_jsons tags_listobservation_scopes_listtext_signals_listtext_search_extensionc KdS)zBatch-insert facts, returning IDs. PG uses INSERT ... SELECT FROM unnest() with RETURNING. Non-PG inserts row-by-row with individual RETURNING. Nr)rr!r-r.r/r0r1r2r3r4r5r6r#r$r7r8r9r:s rinsert_facts_batchz DataAccessOps.insert_facts_batchKs 4 r sorted_linksnil_entity_uuid exists_clause chunk_sizec KdS)zBulk insert memory_links with conflict handling. PG uses INSERT ... SELECT FROM unnest() with chunking. Non-PG uses executemany. Nr)rr!r"r>r-r?r@rAs rbulk_insert_linkszDataAccessOps.bulk_insert_linksg r entity_names entity_datesc KdS)zBulk insert entities with ON CONFLICT DO NOTHING, returning id-by-lowercase-name. PG uses INSERT ... SELECT FROM unnest() with RETURNING. Non-PG inserts row-by-row then SELECTs. Nr)rr!r"r-rErFs rbulk_insert_entitiesz"DataAccessOps.bulk_insert_entitiesy  r missing_namesc KdS)zFetch entity IDs for names that conflicted during insert. PG uses unnest + JOIN. Non-PG queries each name individually. Nr)rr!r"r-rJs rfetch_missing_entity_idsz&DataAccessOps.fetch_missing_entity_ids  runit_ids entity_idsc KdS)zBulk insert unit_entities links with ON CONFLICT DO NOTHING. PG uses INSERT ... SELECT FROM unnest(). Non-PG uses executemany. Nr)rr!r"rNrOs rbulk_insert_unit_entitiesz'DataAccessOps.bulk_insert_unit_entitiesrMrue_tableentity_id_listlimit_per_entityc KdS)zFetch unit_ids for a list of entities with per-entity row cap. PG uses unnest + CROSS JOIN LATERAL with LIMIT. Non-PG queries each entity individually. Nr)rr!rRrSrTs rfetch_entity_unit_fanoutz&DataAccessOps.fetch_entity_unit_fanoutrMrmu_tablec KdS)zFetch event_date/fact_type for a list of unit IDs. PG uses ANY($1) array binding. Non-PG queries each unit individually. Nr)rr!rWrNs rfetch_unit_dateszDataAccessOps.fetch_unit_datess  rlateral_unit_idslateral_event_dateslateral_fact_types half_limit batch_sizec  KdS)zFetch temporal neighbors using bidirectional index scan. PG uses unnest + CROSS JOIN LATERAL for batched bidirectional scan. Non-PG queries each unit individually with backward/forward scans. Nr) rr!rWr-r[r\r]r^r_s rfetch_temporal_neighborsz&DataAccessOps.fetch_temporal_neighborsr+rper_entity_limitcdS)zBuild entity expansion CTE for link expansion retrieval. PG uses DISTINCT ON with CROSS JOIN LATERAL and GROUP BY. Non-PG splits into entity_scores subquery then JOINs for full columns (can't GROUP BY CLOB). Nr)rrWrRrbs rbuild_entity_expansion_ctez(DataAccessOps.build_entity_expansion_ctes  rml_tablecdS)zBuild semantic + causal expansion CTEs. PG uses DISTINCT ON for deduplication. Non-PG computes MAX(weight) in subquery then JOINs for full columns. Nr)rrerWs rbuild_semantic_causal_ctez'DataAccessOps.build_semantic_causal_ctes  rseed_idsbudgetc KdS)zObservation-specific graph expansion. PG uses native array ops (source_memory_ids column) for performance. Oracle uses the observation_sources junction table. Nr)rr!rWrRrerhrirbs rexpand_observationsz!DataAccessOps.expand_observationsrDrcdS)zBuild SQL fragments for the tag listing query. PG uses unnest(tags) to expand the VARCHAR[] column. Non-PG uses CROSS APPLY JSON_TABLE on the CLOB column. Nr)rrWs rbuild_tag_listing_partsz%DataAccessOps.build_tag_listing_parts   r internal_id index_clausec KdS)zCreate per-bank partial vector indexes. PG creates per-(bank, fact_type) partial indexes. Non-PG is a no-op (uses global index). Nr)rr!r"r-rorpr5s rcreate_bank_vector_indexesz(DataAccessOps.create_bank_vector_indexess  rschemac KdS)zzDrop per-bank partial vector indexes. PG drops per-(bank, fact_type) indexes. Non-PG is a no-op. Nr)rr!rsror5s rdrop_bank_vector_indexesz&DataAccessOps.drop_bank_vector_indexes'rMrcdS)zReturn the fuzzy entity matching strategy name. PG uses "trigram" (pg_trgm). Non-PG uses "oracle_fuzzy" (UTL_MATCH) or falls back to "full". Nrrs rget_entity_resolution_strategyz,DataAccessOps.get_entity_resolution_strategy8rnr webhook_idurlsecret event_typesenabledhttp_config_jsonc  KdS)z0Insert a webhook row and return the created row.Nr) rr!r"rxr-ryrzr{r|r}s rcreate_webhookzDataAccessOps.create_webhookCrIrc KdS)z4List all webhooks for a bank, ordered by created_at.Nr)rr!r"r-s rlist_webhooks_for_bankz$DataAccessOps.list_webhooks_for_bankS  r webhook_tablec KdS)zHGet enabled webhooks matching a bank (bank-specific + global NULL rows).Nr)rr!rr-s rget_webhooks_for_dispatchz'DataAccessOps.get_webhooks_for_dispatch]rr set_clausesparamsc KdS)zBUpdate a webhook and return the updated row, or None if not found.Nr)rr!r"rxr-rrs rupdate_webhookzDataAccessOps.update_webhookg  rc KdS)z4Delete a webhook. Returns True if a row was deleted.Nr)rr!r"rxr-s rdelete_webhookzDataAccessOps.delete_webhookts  r ops_tablelimitcursorc KdS)zFList webhook delivery operations for a specific webhook, newest first.Nr)rr!rrxr-rrs rlist_webhook_deliveriesz%DataAccessOps.list_webhook_deliveriesrr operation_id payload_json timestampc KdS)z5Insert a webhook delivery task into async_operations.Nr)rr!rrr-rrs rinsert_webhook_delivery_taskz*DataAccessOps.insert_webhook_delivery_taskrr worker_idreserved_limits shared_limitc KdS)aClaim pending tasks from the async_operations table. PG implementation can use NOT EXISTS + FOR UPDATE SKIP LOCKED in one query. Oracle implementation uses two-step claims (query busy banks first, then claim excluding them) to avoid ORA-02014. Returns claimed rows with operation_id, operation_type, task_payload, retry_count. The caller is responsible for building ClaimedTask objects. Nr)rr!r"rrrs r claim_taskszDataAccessOps.claim_taskss $ rc$ddlm}|dS)z0Get the fully-qualified memory_units table name.)fq_table memory_units)rsr)rrs r _get_mu_tablezDataAccessOps._get_mu_tables$%%%%%%x'''r)r,)r=)rZ)+rrrrpropertyboolr rr rlistintr*r<tuplerCdictrHr rLrQrrVrYrardrgrkr rmrrrurwrrrrrrrrrrrrrrr&s  X    9  3i  s)  #Y Cy S      ^ $&&.%     I  I       s) I S    9 "&! " # $ #% & c'   ^ 6     5k            ^ "         3i     c3h    ^           Cy  i    ^                 ^         T    i    ^         s)  i    ^           "  !    i   ^ (           ^            ^               tIYi@ A   ^ &     ^           cN     ^          cN      ^      ^              d   #Y       T     ^        i    ^       i    ^            #Y  S    T     ^              ^              d    i    ^                      ^        c3h     i   ^ *(s((((((rrN)rabcrr dataclassesrtypingruuidrbaser resultr r rrrrrs$$#######!!!!!!$$$$$$  O(O(O(O(O(CO(O(O(O(O(r