sqlspec 0.60.0__py3-none-any.whl → 0.61.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.
Files changed (56) hide show
  1. sqlspec/adapters/adbc/adk/store.py +178 -78
  2. sqlspec/adapters/aiomysql/adk/store.py +105 -39
  3. sqlspec/adapters/aiomysql/driver.py +36 -0
  4. sqlspec/adapters/aiosqlite/adk/store.py +107 -36
  5. sqlspec/adapters/arrow_odbc/adk/store.py +113 -63
  6. sqlspec/adapters/asyncmy/adk/store.py +102 -39
  7. sqlspec/adapters/asyncmy/driver.py +36 -0
  8. sqlspec/adapters/asyncpg/adk/store.py +182 -56
  9. sqlspec/adapters/bigquery/adk/store.py +48 -27
  10. sqlspec/adapters/cockroach_asyncpg/adk/store.py +127 -45
  11. sqlspec/adapters/cockroach_psycopg/adk/store.py +207 -84
  12. sqlspec/adapters/duckdb/adk/store.py +162 -98
  13. sqlspec/adapters/mssql_python/adk/store.py +42 -21
  14. sqlspec/adapters/mysqlconnector/adk/store.py +158 -74
  15. sqlspec/adapters/mysqlconnector/driver.py +38 -0
  16. sqlspec/adapters/oracledb/_storage.py +20 -102
  17. sqlspec/adapters/oracledb/adk/store.py +262 -142
  18. sqlspec/adapters/oracledb/data_dictionary.py +2 -107
  19. sqlspec/adapters/oracledb/events/store.py +1 -15
  20. sqlspec/adapters/oracledb/litestar/store.py +1 -15
  21. sqlspec/adapters/psqlpy/adk/store.py +134 -49
  22. sqlspec/adapters/psycopg/adk/store.py +475 -163
  23. sqlspec/adapters/psycopg/driver.py +41 -0
  24. sqlspec/adapters/pymssql/adk/store.py +100 -45
  25. sqlspec/adapters/pymysql/adk/store.py +111 -58
  26. sqlspec/adapters/pymysql/driver.py +36 -0
  27. sqlspec/adapters/spanner/adk/store.py +164 -97
  28. sqlspec/adapters/sqlite/adk/store.py +122 -84
  29. sqlspec/config.py +15 -0
  30. sqlspec/data_dictionary/dialects/oracle/sql/version.sql +0 -6
  31. sqlspec/driver/_async.py +5 -1
  32. sqlspec/driver/_common.py +9 -1
  33. sqlspec/driver/_sync.py +5 -1
  34. sqlspec/extensions/adk/__init__.py +31 -37
  35. sqlspec/extensions/adk/_config_utils.py +10 -0
  36. sqlspec/extensions/adk/_types.py +3 -3
  37. sqlspec/extensions/adk/artifact/__init__.py +3 -3
  38. sqlspec/extensions/adk/artifact/_types.py +2 -2
  39. sqlspec/extensions/adk/artifact/service.py +3 -3
  40. sqlspec/extensions/adk/artifact/store.py +9 -9
  41. sqlspec/extensions/adk/converters.py +15 -9
  42. sqlspec/extensions/adk/maintenance.py +168 -0
  43. sqlspec/extensions/adk/memory/__init__.py +3 -36
  44. sqlspec/extensions/adk/memory/_types.py +8 -3
  45. sqlspec/extensions/adk/memory/converters.py +55 -20
  46. sqlspec/extensions/adk/memory/service.py +53 -16
  47. sqlspec/extensions/adk/memory/store.py +199 -216
  48. sqlspec/extensions/adk/migrations/0001_create_adk_tables.py +121 -8
  49. sqlspec/extensions/adk/migrations/0002_reset_adk_tables.py +5 -4
  50. sqlspec/extensions/adk/store.py +43 -29
  51. sqlspec/utils/arrow_helpers.py +76 -15
  52. {sqlspec-0.60.0.dist-info → sqlspec-0.61.0.dist-info}/METADATA +1 -1
  53. {sqlspec-0.60.0.dist-info → sqlspec-0.61.0.dist-info}/RECORD +56 -55
  54. {sqlspec-0.60.0.dist-info → sqlspec-0.61.0.dist-info}/WHEEL +0 -0
  55. {sqlspec-0.60.0.dist-info → sqlspec-0.61.0.dist-info}/entry_points.txt +0 -0
  56. {sqlspec-0.60.0.dist-info → sqlspec-0.61.0.dist-info}/licenses/LICENSE +0 -0
@@ -3,16 +3,18 @@
3
3
  import contextlib
4
4
  import re
5
5
  from datetime import datetime, timedelta, timezone
6
- from typing import TYPE_CHECKING, Any, Final
6
+ from typing import TYPE_CHECKING, Any, Final, Literal
7
7
 
8
- from sqlspec.extensions.adk import BaseSyncADKStore, EventRecord, SessionRecord
8
+ from sqlspec.extensions.adk import BaseSyncADKStore, StoredEvent, StoredSession
9
9
  from sqlspec.extensions.adk.memory.store import BaseSyncADKMemoryStore
10
10
  from sqlspec.utils.logging import get_logger
11
11
  from sqlspec.utils.serializers import from_json, to_json
12
12
 
13
13
  if TYPE_CHECKING:
14
+ from collections.abc import Sequence
15
+
14
16
  from sqlspec.adapters.adbc.config import AdbcConfig
15
- from sqlspec.extensions.adk import MemoryRecord
17
+ from sqlspec.extensions.adk import StoredMemory
16
18
 
17
19
  __all__ = ("AdbcADKMemoryStore", "AdbcADKStore")
18
20
 
@@ -80,13 +82,13 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
80
82
 
81
83
  def create_session(
82
84
  self, session_id: str, app_name: str, user_id: str, state: "dict[str, Any]", owner_id: "Any | None" = None
83
- ) -> SessionRecord:
85
+ ) -> StoredSession:
84
86
  """Create a new session."""
85
87
  return self._create_session(session_id, app_name, user_id, state, owner_id)
86
88
 
87
89
  def get_session(
88
90
  self, app_name: str, user_id: str, session_id: str, *, renew_for: "int | timedelta | None" = None
89
- ) -> "SessionRecord | None":
91
+ ) -> "StoredSession | None":
90
92
  """Get session by ID."""
91
93
  return self._get_session(app_name, user_id, session_id, renew_for=renew_for)
92
94
 
@@ -94,7 +96,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
94
96
  """Update session state."""
95
97
  self._update_session_state(app_name, user_id, session_id, state)
96
98
 
97
- def list_sessions(self, app_name: str, user_id: str | None = None) -> "list[SessionRecord]":
99
+ def list_sessions(self, app_name: str, user_id: str | None = None) -> "list[StoredSession]":
98
100
  """List sessions for an app."""
99
101
  return self._list_sessions(app_name, user_id)
100
102
 
@@ -102,13 +104,13 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
102
104
  """Delete session and associated events."""
103
105
  self._delete_session(app_name, user_id, session_id)
104
106
 
105
- def append_event(self, event_record: EventRecord) -> None:
107
+ def append_event(self, event_record: StoredEvent) -> None:
106
108
  """Append an event to a session."""
107
109
  self._append_event(event_record)
108
110
 
109
111
  def append_event_and_update_state(
110
112
  self,
111
- event_record: EventRecord,
113
+ event_record: StoredEvent,
112
114
  app_name: str,
113
115
  user_id: str,
114
116
  session_id: str,
@@ -116,7 +118,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
116
118
  *,
117
119
  app_state: "dict[str, Any] | None" = None,
118
120
  user_state: "dict[str, Any] | None" = None,
119
- ) -> SessionRecord:
121
+ ) -> StoredSession:
120
122
  """Atomically append an event and update the session's durable state."""
121
123
  return self._append_event_and_update_state(
122
124
  event_record, app_name, user_id, session_id, state, app_state=app_state, user_state=user_state
@@ -129,17 +131,21 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
129
131
  session_id: str,
130
132
  after_timestamp: "datetime | None" = None,
131
133
  limit: "int | None" = None,
132
- ) -> "list[EventRecord]":
134
+ ) -> "list[StoredEvent]":
133
135
  """Get events for a session."""
134
136
  return self._get_events(app_name, user_id, session_id, after_timestamp, limit)
135
137
 
136
- def delete_expired_events(self, before: datetime) -> int:
138
+ def delete_expired_events(self, before: datetime, app_name: "str | None" = None) -> int:
137
139
  """Delete events older than a timestamp."""
138
- return self._delete_expired_events(before)
140
+ return self._delete_expired_events(before, app_name)
139
141
 
140
- def delete_idle_sessions(self, updated_before: datetime) -> int:
142
+ def delete_idle_sessions(self, updated_before: datetime, app_name: "str | None" = None) -> int:
141
143
  """Delete sessions older than a timestamp."""
142
- return self._delete_idle_sessions(updated_before)
144
+ return self._delete_idle_sessions(updated_before, app_name)
145
+
146
+ def delete_idle_user_states(self, updated_before: datetime, app_name: "str | None" = None) -> int:
147
+ """Delete user state rows older than a timestamp."""
148
+ return self._delete_idle_user_states(updated_before, app_name)
143
149
 
144
150
  def get_app_state(self, app_name: str) -> "dict[str, Any] | None":
145
151
  """Return app-scoped state."""
@@ -390,6 +396,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
390
396
  return f"""
391
397
  CREATE TABLE IF NOT EXISTS {self._events_table} (
392
398
  id VARCHAR(128) PRIMARY KEY,
399
+ app_name VARCHAR(128) NOT NULL,
400
+ user_id VARCHAR(128) NOT NULL,
393
401
  session_id VARCHAR(128) NOT NULL,
394
402
  invocation_id VARCHAR(256),
395
403
  timestamp TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -407,6 +415,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
407
415
  return f"""
408
416
  CREATE TABLE IF NOT EXISTS {self._events_table} (
409
417
  id TEXT PRIMARY KEY,
418
+ app_name TEXT NOT NULL,
419
+ user_id TEXT NOT NULL,
410
420
  session_id TEXT NOT NULL,
411
421
  invocation_id TEXT,
412
422
  timestamp REAL NOT NULL,
@@ -424,6 +434,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
424
434
  return f"""
425
435
  CREATE TABLE IF NOT EXISTS {self._events_table} (
426
436
  id VARCHAR(128) PRIMARY KEY,
437
+ app_name VARCHAR(128) NOT NULL,
438
+ user_id VARCHAR(128) NOT NULL,
427
439
  session_id VARCHAR(128) NOT NULL,
428
440
  invocation_id VARCHAR(256),
429
441
  timestamp TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -441,6 +453,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
441
453
  return f"""
442
454
  CREATE TABLE IF NOT EXISTS {self._events_table} (
443
455
  id VARCHAR PRIMARY KEY,
456
+ app_name VARCHAR NOT NULL,
457
+ user_id VARCHAR NOT NULL,
444
458
  session_id VARCHAR NOT NULL,
445
459
  invocation_id VARCHAR,
446
460
  timestamp TIMESTAMP_TZ NOT NULL DEFAULT CURRENT_TIMESTAMP(),
@@ -458,6 +472,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
458
472
  return f"""
459
473
  CREATE TABLE IF NOT EXISTS {self._events_table} (
460
474
  id VARCHAR(128) PRIMARY KEY,
475
+ app_name VARCHAR(128) NOT NULL,
476
+ user_id VARCHAR(128) NOT NULL,
461
477
  session_id VARCHAR(128) NOT NULL,
462
478
  invocation_id VARCHAR(256),
463
479
  timestamp TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -599,7 +615,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
599
615
 
600
616
  def _create_session(
601
617
  self, session_id: str, app_name: str, user_id: str, state: "dict[str, Any]", owner_id: "Any | None" = None
602
- ) -> SessionRecord:
618
+ ) -> StoredSession:
603
619
  """Create a new session.
604
620
 
605
621
  Args:
@@ -646,7 +662,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
646
662
 
647
663
  def _get_session(
648
664
  self, app_name: str, user_id: str, session_id: str, *, renew_for: "int | timedelta | None" = None
649
- ) -> "SessionRecord | None":
665
+ ) -> "StoredSession | None":
650
666
  """Get session by ID.
651
667
 
652
668
  Args:
@@ -696,7 +712,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
696
712
  if row is None:
697
713
  return None
698
714
 
699
- return SessionRecord(
715
+ return StoredSession(
700
716
  id=row[0],
701
717
  app_name=row[1],
702
718
  user_id=row[2],
@@ -759,7 +775,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
759
775
  finally:
760
776
  cursor.close()
761
777
 
762
- def _list_sessions(self, app_name: str, user_id: str | None = None) -> "list[SessionRecord]":
778
+ def _list_sessions(self, app_name: str, user_id: str | None = None) -> "list[StoredSession]":
763
779
  """List sessions for an app, optionally filtered by user.
764
780
 
765
781
  Args:
@@ -794,7 +810,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
794
810
  rows = cursor.fetchall()
795
811
 
796
812
  return [
797
- SessionRecord(
813
+ StoredSession(
798
814
  id=row[0],
799
815
  app_name=row[1],
800
816
  user_id=row[2],
@@ -812,7 +828,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
812
828
  return []
813
829
  raise
814
830
 
815
- def _insert_event(self, event_record: "EventRecord") -> None:
831
+ def _insert_event(self, event_record: "StoredEvent") -> None:
816
832
  """Insert an event record into the events table.
817
833
 
818
834
  Args:
@@ -821,8 +837,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
821
837
  event_data = self._serialize_json_field(event_record["event_data"])
822
838
  sql = f"""
823
839
  INSERT INTO {self._events_table} (
824
- id, session_id, invocation_id, timestamp, event_data
825
- ) VALUES (?, ?, ?, ?, {self._json_placeholder()})
840
+ id, app_name, user_id, session_id, invocation_id, timestamp, event_data
841
+ ) VALUES (?, ?, ?, ?, ?, ?, {self._json_placeholder()})
826
842
  """
827
843
 
828
844
  with self._config.provide_connection() as conn:
@@ -833,6 +849,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
833
849
  sql,
834
850
  (
835
851
  event_record["id"],
852
+ event_record["app_name"],
853
+ event_record["user_id"],
836
854
  event_record["session_id"],
837
855
  event_record["invocation_id"],
838
856
  event_record["timestamp"],
@@ -845,7 +863,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
845
863
 
846
864
  def _append_event_and_update_state(
847
865
  self,
848
- event_record: "EventRecord",
866
+ event_record: "StoredEvent",
849
867
  app_name: str,
850
868
  user_id: str,
851
869
  session_id: str,
@@ -853,7 +871,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
853
871
  *,
854
872
  app_state: "dict[str, Any] | None" = None,
855
873
  user_state: "dict[str, Any] | None" = None,
856
- ) -> SessionRecord:
874
+ ) -> StoredSession:
857
875
  """Atomically insert an event and update the session's durable state.
858
876
 
859
877
  The event insert, state update, and refresh-SELECT are executed within
@@ -874,8 +892,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
874
892
  """
875
893
  insert_sql = f"""
876
894
  INSERT INTO {self._events_table} (
877
- id, session_id, invocation_id, timestamp, event_data
878
- ) VALUES (?, ?, ?, ?, {self._json_placeholder()})
895
+ id, app_name, user_id, session_id, invocation_id, timestamp, event_data
896
+ ) VALUES (?, ?, ?, ?, ?, ?, {self._json_placeholder()})
879
897
  """
880
898
  update_sql = f"""
881
899
  UPDATE {self._session_table}
@@ -908,6 +926,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
908
926
  insert_sql,
909
927
  (
910
928
  event_record["id"],
929
+ event_record["app_name"],
930
+ event_record["user_id"],
911
931
  event_record["session_id"],
912
932
  event_record["invocation_id"],
913
933
  event_record["timestamp"],
@@ -943,7 +963,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
943
963
  msg = f"Session {session_id} not found during append_event_and_update_state."
944
964
  raise ValueError(msg)
945
965
 
946
- return SessionRecord(
966
+ return StoredSession(
947
967
  id=row[0],
948
968
  app_name=row[1],
949
969
  user_id=row[2],
@@ -959,7 +979,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
959
979
  session_id: str,
960
980
  after_timestamp: "datetime | None" = None,
961
981
  limit: "int | None" = None,
962
- ) -> "list[EventRecord]":
982
+ ) -> "list[StoredEvent]":
963
983
  """List events for a session ordered by timestamp.
964
984
 
965
985
  Args:
@@ -1000,7 +1020,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
1000
1020
  rows = cursor.fetchall()
1001
1021
 
1002
1022
  return [
1003
- EventRecord(
1023
+ StoredEvent(
1004
1024
  id=row[0],
1005
1025
  session_id=row[1],
1006
1026
  invocation_id=row[2] or "",
@@ -1019,18 +1039,23 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
1019
1039
  return []
1020
1040
  raise
1021
1041
 
1022
- def _delete_expired_events(self, before: datetime) -> int:
1023
- count_sql = f"SELECT COUNT(*) FROM {self._events_table} WHERE timestamp < ?"
1024
- delete_sql = f"DELETE FROM {self._events_table} WHERE timestamp < ?"
1042
+ def _delete_expired_events(self, before: datetime, app_name: "str | None" = None) -> int:
1043
+ where = "WHERE timestamp < ?"
1044
+ params: tuple[Any, ...] = (before,)
1045
+ if app_name is not None:
1046
+ where += " AND app_name = ?"
1047
+ params = (before, app_name)
1048
+ count_sql = f"SELECT COUNT(*) FROM {self._events_table} {where}"
1049
+ delete_sql = f"DELETE FROM {self._events_table} {where}"
1025
1050
 
1026
1051
  try:
1027
1052
  with self._config.provide_connection() as conn:
1028
1053
  cursor = conn.cursor()
1029
1054
  try:
1030
- self._execute(cursor, count_sql, (before,))
1055
+ self._execute(cursor, count_sql, params)
1031
1056
  row = cursor.fetchone()
1032
1057
  count = int(row[0]) if row is not None else 0
1033
- self._execute(cursor, delete_sql, (before,))
1058
+ self._execute(cursor, delete_sql, params)
1034
1059
  conn.commit()
1035
1060
  return count
1036
1061
  finally:
@@ -1041,23 +1066,55 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
1041
1066
  return 0
1042
1067
  raise
1043
1068
 
1044
- def _delete_idle_sessions(self, updated_before: datetime) -> int:
1045
- count_sql = f"SELECT COUNT(*) FROM {self._session_table} WHERE update_time < ?"
1069
+ def _delete_idle_sessions(self, updated_before: datetime, app_name: "str | None" = None) -> int:
1070
+ where = "WHERE update_time < ?"
1071
+ params: tuple[Any, ...] = (updated_before,)
1072
+ if app_name is not None:
1073
+ where += " AND app_name = ?"
1074
+ params = (updated_before, app_name)
1075
+ count_sql = f"SELECT COUNT(*) FROM {self._session_table} {where}"
1046
1076
  delete_events_sql = f"""
1047
1077
  DELETE FROM {self._events_table}
1048
- WHERE session_id IN (SELECT id FROM {self._session_table} WHERE update_time < ?)
1078
+ WHERE session_id IN (SELECT id FROM {self._session_table} {where})
1049
1079
  """
1050
- delete_sessions_sql = f"DELETE FROM {self._session_table} WHERE update_time < ?"
1080
+ delete_sessions_sql = f"DELETE FROM {self._session_table} {where}"
1051
1081
 
1052
1082
  try:
1053
1083
  with self._config.provide_connection() as conn:
1054
1084
  cursor = conn.cursor()
1055
1085
  try:
1056
- self._execute(cursor, count_sql, (updated_before,))
1086
+ self._execute(cursor, count_sql, params)
1057
1087
  row = cursor.fetchone()
1058
1088
  count = int(row[0]) if row is not None else 0
1059
- self._execute(cursor, delete_events_sql, (updated_before,))
1060
- self._execute(cursor, delete_sessions_sql, (updated_before,))
1089
+ self._execute(cursor, delete_events_sql, params)
1090
+ self._execute(cursor, delete_sessions_sql, params)
1091
+ conn.commit()
1092
+ return count
1093
+ finally:
1094
+ cursor.close()
1095
+ except Exception as exc:
1096
+ error_msg = str(exc).lower()
1097
+ if any(pattern in error_msg for pattern in ADBC_TABLE_NOT_FOUND_PATTERNS):
1098
+ return 0
1099
+ raise
1100
+
1101
+ def _delete_idle_user_states(self, updated_before: datetime, app_name: "str | None" = None) -> int:
1102
+ where = "WHERE update_time < ?"
1103
+ params: tuple[Any, ...] = (updated_before,)
1104
+ if app_name is not None:
1105
+ where += " AND app_name = ?"
1106
+ params = (updated_before, app_name)
1107
+ count_sql = f"SELECT COUNT(*) FROM {self._user_state_table} {where}"
1108
+ delete_sql = f"DELETE FROM {self._user_state_table} {where}"
1109
+
1110
+ try:
1111
+ with self._config.provide_connection() as conn:
1112
+ cursor = conn.cursor()
1113
+ try:
1114
+ self._execute(cursor, count_sql, params)
1115
+ row = cursor.fetchone()
1116
+ count = int(row[0]) if row is not None else 0
1117
+ self._execute(cursor, delete_sql, params)
1061
1118
  conn.commit()
1062
1119
  return count
1063
1120
  finally:
@@ -1160,7 +1217,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
1160
1217
  finally:
1161
1218
  cursor.close()
1162
1219
 
1163
- def _append_event(self, event_record: EventRecord) -> None:
1220
+ def _append_event(self, event_record: StoredEvent) -> None:
1164
1221
  """Synchronous implementation of append_event."""
1165
1222
  self._insert_event(event_record)
1166
1223
 
@@ -1186,23 +1243,29 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1186
1243
 
1187
1244
  self._create_tables()
1188
1245
 
1189
- def insert_memory_entries(self, entries: "list[MemoryRecord]", owner_id: "object | None" = None) -> int:
1246
+ def insert_memory_entries(self, entries: "list[StoredMemory]", owner_id: "object | None" = None) -> int:
1190
1247
  """Bulk insert memory entries with deduplication."""
1191
1248
  return self._insert_memory_entries(entries, owner_id)
1192
1249
 
1193
1250
  def search_entries(
1194
- self, query: str, app_name: str, user_id: str, limit: "int | None" = None
1195
- ) -> "list[MemoryRecord]":
1251
+ self,
1252
+ query: str,
1253
+ app_name: str,
1254
+ user_id: str,
1255
+ limit: "int | None" = None,
1256
+ scope_filter: Literal["all", "user", "app"] = "all",
1257
+ embedding: "Sequence[float] | None" = None,
1258
+ ) -> "list[StoredMemory]":
1196
1259
  """Search memory entries by text query."""
1197
- return self._search_entries(query, app_name, user_id, limit)
1260
+ return self._search_entries(query, app_name, user_id, limit, scope_filter)
1198
1261
 
1199
1262
  def delete_entries_by_session(self, session_id: str) -> int:
1200
1263
  """Delete all memory entries for a specific session."""
1201
1264
  return self._delete_entries_by_session(session_id)
1202
1265
 
1203
- def delete_entries_older_than(self, days: int) -> int:
1266
+ def delete_entries_older_than(self, days: int, app_name: "str | None" = None, scope: "str | None" = None) -> int:
1204
1267
  """Delete memory entries older than specified days."""
1205
- return self._delete_entries_older_than(days)
1268
+ return self._delete_entries_older_than(days, app_name, scope)
1206
1269
 
1207
1270
  def _detect_dialect(self) -> str:
1208
1271
  driver_name = self._config.connection_config.get("driver_name", "").lower()
@@ -1255,6 +1318,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1255
1318
  session_id VARCHAR(128) NOT NULL,
1256
1319
  app_name VARCHAR(128) NOT NULL,
1257
1320
  user_id VARCHAR(128) NOT NULL,
1321
+ scope VARCHAR(16) NOT NULL DEFAULT 'user',
1258
1322
  event_id VARCHAR(128) NOT NULL UNIQUE,
1259
1323
  author VARCHAR(256){owner_id_ddl},
1260
1324
  timestamp TIMESTAMPTZ NOT NULL,
@@ -1273,6 +1337,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1273
1337
  session_id TEXT NOT NULL,
1274
1338
  app_name TEXT NOT NULL,
1275
1339
  user_id TEXT NOT NULL,
1340
+ scope TEXT NOT NULL DEFAULT 'user',
1276
1341
  event_id TEXT NOT NULL UNIQUE,
1277
1342
  author TEXT{owner_id_ddl},
1278
1343
  timestamp REAL NOT NULL,
@@ -1291,6 +1356,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1291
1356
  session_id VARCHAR(128) NOT NULL,
1292
1357
  app_name VARCHAR(128) NOT NULL,
1293
1358
  user_id VARCHAR(128) NOT NULL,
1359
+ scope VARCHAR(16) NOT NULL DEFAULT 'user',
1294
1360
  event_id VARCHAR(128) NOT NULL UNIQUE,
1295
1361
  author VARCHAR(256){owner_id_ddl},
1296
1362
  timestamp TIMESTAMP NOT NULL,
@@ -1309,6 +1375,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1309
1375
  session_id VARCHAR NOT NULL,
1310
1376
  app_name VARCHAR NOT NULL,
1311
1377
  user_id VARCHAR NOT NULL,
1378
+ scope VARCHAR NOT NULL DEFAULT 'user',
1312
1379
  event_id VARCHAR NOT NULL UNIQUE,
1313
1380
  author VARCHAR{owner_id_ddl},
1314
1381
  timestamp TIMESTAMP_TZ NOT NULL,
@@ -1327,6 +1394,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1327
1394
  session_id VARCHAR(128) NOT NULL,
1328
1395
  app_name VARCHAR(128) NOT NULL,
1329
1396
  user_id VARCHAR(128) NOT NULL,
1397
+ scope VARCHAR(16) NOT NULL DEFAULT 'user',
1330
1398
  event_id VARCHAR(128) NOT NULL UNIQUE,
1331
1399
  author VARCHAR(256){owner_id_ddl},
1332
1400
  timestamp TIMESTAMP NOT NULL,
@@ -1350,8 +1418,12 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1350
1418
  cursor.execute(self._memory_table_ddl())
1351
1419
  conn.commit()
1352
1420
 
1353
- idx_app_user = f"CREATE INDEX IF NOT EXISTS idx_{self._memory_table}_app_user_time ON {self._memory_table}(app_name, user_id, timestamp DESC)"
1354
- cursor.execute(idx_app_user)
1421
+ idx_app_scope_user = f"CREATE INDEX IF NOT EXISTS idx_{self._memory_table}_app_scope_user_time ON {self._memory_table}(app_name, scope, user_id, timestamp DESC)"
1422
+ cursor.execute(idx_app_scope_user)
1423
+ conn.commit()
1424
+
1425
+ idx_scope = f"CREATE INDEX IF NOT EXISTS idx_{self._memory_table}_scope ON {self._memory_table}(app_name, scope)"
1426
+ cursor.execute(idx_scope)
1355
1427
  conn.commit()
1356
1428
 
1357
1429
  idx_session = (
@@ -1362,7 +1434,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1362
1434
  finally:
1363
1435
  cursor.close()
1364
1436
 
1365
- def _insert_memory_entries(self, entries: "list[MemoryRecord]", owner_id: "object | None" = None) -> int:
1437
+ def _insert_memory_entries(self, entries: "list[StoredMemory]", owner_id: "object | None" = None) -> int:
1366
1438
  if not self._enabled:
1367
1439
  msg = "Memory store is disabled"
1368
1440
  raise RuntimeError(msg)
@@ -1377,39 +1449,39 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1377
1449
  if use_returning:
1378
1450
  sql = f"""
1379
1451
  INSERT INTO {self._memory_table} (
1380
- id, session_id, app_name, user_id, event_id, author,
1452
+ id, session_id, app_name, user_id, scope, event_id, author,
1381
1453
  {self._owner_id_column_name}, timestamp, content_json, content_text,
1382
1454
  metadata_json, inserted_at
1383
1455
  ) VALUES (
1384
- ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1456
+ ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1385
1457
  ) ON CONFLICT(event_id) DO NOTHING RETURNING 1
1386
1458
  """
1387
1459
  else:
1388
1460
  sql = f"""
1389
1461
  INSERT INTO {self._memory_table} (
1390
- id, session_id, app_name, user_id, event_id, author,
1462
+ id, session_id, app_name, user_id, scope, event_id, author,
1391
1463
  {self._owner_id_column_name}, timestamp, content_json, content_text,
1392
1464
  metadata_json, inserted_at
1393
1465
  ) VALUES (
1394
- ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1466
+ ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1395
1467
  )
1396
1468
  """
1397
1469
  elif use_returning:
1398
1470
  sql = f"""
1399
1471
  INSERT INTO {self._memory_table} (
1400
- id, session_id, app_name, user_id, event_id, author,
1472
+ id, session_id, app_name, user_id, scope, event_id, author,
1401
1473
  timestamp, content_json, content_text, metadata_json, inserted_at
1402
1474
  ) VALUES (
1403
- ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1475
+ ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1404
1476
  ) ON CONFLICT(event_id) DO NOTHING RETURNING 1
1405
1477
  """
1406
1478
  else:
1407
1479
  sql = f"""
1408
1480
  INSERT INTO {self._memory_table} (
1409
- id, session_id, app_name, user_id, event_id, author,
1481
+ id, session_id, app_name, user_id, scope, event_id, author,
1410
1482
  timestamp, content_json, content_text, metadata_json, inserted_at
1411
1483
  ) VALUES (
1412
- ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1484
+ ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1413
1485
  )
1414
1486
  """
1415
1487
 
@@ -1426,6 +1498,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1426
1498
  entry["session_id"],
1427
1499
  entry["app_name"],
1428
1500
  entry["user_id"],
1501
+ entry.get("scope", "user"),
1429
1502
  entry["event_id"],
1430
1503
  entry["author"],
1431
1504
  owner_id,
@@ -1441,6 +1514,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1441
1514
  entry["session_id"],
1442
1515
  entry["app_name"],
1443
1516
  entry["user_id"],
1517
+ entry.get("scope", "user"),
1444
1518
  entry["event_id"],
1445
1519
  entry["author"],
1446
1520
  self._encode_timestamp(entry["timestamp"]),
@@ -1469,8 +1543,13 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1469
1543
  return inserted_count
1470
1544
 
1471
1545
  def _search_entries(
1472
- self, query: str, app_name: str, user_id: str, limit: "int | None" = None
1473
- ) -> "list[MemoryRecord]":
1546
+ self,
1547
+ query: str,
1548
+ app_name: str,
1549
+ user_id: str,
1550
+ limit: "int | None" = None,
1551
+ scope_filter: Literal["all", "user", "app"] = "all",
1552
+ ) -> "list[StoredMemory]":
1474
1553
  if not self._enabled:
1475
1554
  msg = "Memory store is disabled"
1476
1555
  raise RuntimeError(msg)
@@ -1480,13 +1559,13 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1480
1559
 
1481
1560
  effective_limit = limit if limit is not None else self._max_results
1482
1561
  pattern = f"%{query}%"
1562
+ where_scope, scope_params = _build_adbc_scope_where(app_name, user_id, scope_filter)
1483
1563
 
1484
1564
  sql = f"""
1485
- SELECT id, session_id, app_name, user_id, event_id, author,
1565
+ SELECT id, session_id, app_name, user_id, scope, event_id, author,
1486
1566
  timestamp, content_json, content_text, metadata_json, inserted_at
1487
1567
  FROM {self._memory_table}
1488
- WHERE app_name = ?
1489
- AND user_id = ?
1568
+ WHERE {where_scope}
1490
1569
  AND content_text LIKE ?
1491
1570
  ORDER BY timestamp DESC
1492
1571
  LIMIT ?
@@ -1496,7 +1575,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1496
1575
  with self._config.provide_connection() as conn:
1497
1576
  cursor = conn.cursor()
1498
1577
  try:
1499
- cursor.execute(sql, (app_name, user_id, pattern, effective_limit))
1578
+ cursor.execute(sql, (*scope_params, pattern, effective_limit))
1500
1579
  rows = cursor.fetchall()
1501
1580
  finally:
1502
1581
  cursor.close()
@@ -1527,17 +1606,26 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1527
1606
  finally:
1528
1607
  cursor.close()
1529
1608
 
1530
- def _delete_entries_older_than(self, days: int) -> int:
1609
+ def _delete_entries_older_than(self, days: int, app_name: "str | None" = None, scope: "str | None" = None) -> int:
1531
1610
  cutoff = self._encode_timestamp(datetime.now(timezone.utc) - timedelta(days=days))
1532
1611
  use_returning = self._dialect in {DIALECT_SQLITE, DIALECT_POSTGRESQL, DIALECT_DUCKDB}
1612
+ clauses = ["inserted_at < ?"]
1613
+ params: list[Any] = [cutoff]
1614
+ if app_name is not None:
1615
+ clauses.append("app_name = ?")
1616
+ params.append(app_name)
1617
+ if scope is not None:
1618
+ clauses.append("scope = ?")
1619
+ params.append(scope)
1620
+ where_sql = " AND ".join(clauses)
1533
1621
  if use_returning:
1534
- sql = f"DELETE FROM {self._memory_table} WHERE inserted_at < ? RETURNING 1"
1622
+ sql = f"DELETE FROM {self._memory_table} WHERE {where_sql} RETURNING 1"
1535
1623
  else:
1536
- sql = f"DELETE FROM {self._memory_table} WHERE inserted_at < ?"
1624
+ sql = f"DELETE FROM {self._memory_table} WHERE {where_sql}"
1537
1625
  with self._config.provide_connection() as conn:
1538
1626
  cursor = conn.cursor()
1539
1627
  try:
1540
- cursor.execute(sql, (cutoff,))
1628
+ cursor.execute(sql, tuple(params))
1541
1629
  if use_returning:
1542
1630
  deleted_rows = cursor.fetchall()
1543
1631
  conn.commit()
@@ -1547,16 +1635,16 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1547
1635
  finally:
1548
1636
  cursor.close()
1549
1637
 
1550
- def _rows_to_records(self, rows: "list[Any]") -> "list[MemoryRecord]":
1551
- records: list[MemoryRecord] = []
1638
+ def _rows_to_records(self, rows: "list[Any]") -> "list[StoredMemory]":
1639
+ records: list[StoredMemory] = []
1552
1640
  for row in rows:
1553
- content_json = row[7]
1641
+ content_json = row[8]
1554
1642
  if isinstance(content_json, dict):
1555
1643
  content_value = content_json
1556
1644
  else:
1557
1645
  content_value = from_json(content_json if isinstance(content_json, (str, bytes)) else str(content_json))
1558
1646
 
1559
- metadata_json = row[9]
1647
+ metadata_json = row[10]
1560
1648
  if metadata_json is None:
1561
1649
  metadata_value = None
1562
1650
  elif isinstance(metadata_json, dict):
@@ -1571,12 +1659,24 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1571
1659
  "session_id": row[1],
1572
1660
  "app_name": row[2],
1573
1661
  "user_id": row[3],
1574
- "event_id": row[4],
1575
- "author": row[5],
1576
- "timestamp": self._decode_timestamp(row[6]),
1662
+ "scope": row[4],
1663
+ "event_id": row[5],
1664
+ "author": row[6],
1665
+ "timestamp": self._decode_timestamp(row[7]),
1577
1666
  "content_json": content_value,
1578
- "content_text": row[8],
1667
+ "content_text": row[9],
1579
1668
  "metadata_json": metadata_value,
1580
- "inserted_at": self._decode_timestamp(row[10]),
1669
+ "inserted_at": self._decode_timestamp(row[11]),
1670
+ "embedding": None,
1581
1671
  })
1582
1672
  return records
1673
+
1674
+
1675
+ def _build_adbc_scope_where(
1676
+ app_name: str, user_id: str, scope_filter: Literal["all", "user", "app"]
1677
+ ) -> tuple[str, tuple[Any, ...]]:
1678
+ if scope_filter == "all":
1679
+ return "app_name = ? AND ((scope = 'user' AND user_id = ?) OR scope = 'app')", (app_name, user_id)
1680
+ if scope_filter == "user":
1681
+ return "app_name = ? AND scope = 'user' AND user_id = ?", (app_name, user_id)
1682
+ return "app_name = ? AND scope = 'app'", (app_name,)