sqlspec 0.60.0__py3-none-any.whl → 0.62.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 (69) hide show
  1. sqlspec/adapters/adbc/adk/store.py +236 -96
  2. sqlspec/adapters/aiomysql/adk/store.py +151 -55
  3. sqlspec/adapters/aiomysql/core.py +10 -10
  4. sqlspec/adapters/aiomysql/driver.py +36 -0
  5. sqlspec/adapters/aiosqlite/adk/store.py +158 -53
  6. sqlspec/adapters/aiosqlite/core.py +8 -8
  7. sqlspec/adapters/arrow_odbc/adk/store.py +160 -79
  8. sqlspec/adapters/asyncmy/adk/store.py +148 -55
  9. sqlspec/adapters/asyncmy/core.py +10 -10
  10. sqlspec/adapters/asyncmy/driver.py +36 -0
  11. sqlspec/adapters/asyncpg/adk/store.py +214 -72
  12. sqlspec/adapters/asyncpg/core.py +14 -13
  13. sqlspec/adapters/bigquery/adk/store.py +80 -29
  14. sqlspec/adapters/cockroach_asyncpg/adk/store.py +160 -61
  15. sqlspec/adapters/cockroach_psycopg/adk/store.py +275 -116
  16. sqlspec/adapters/duckdb/adk/store.py +225 -116
  17. sqlspec/adapters/mssql_python/adk/store.py +89 -37
  18. sqlspec/adapters/mysqlconnector/adk/store.py +228 -108
  19. sqlspec/adapters/mysqlconnector/core.py +8 -8
  20. sqlspec/adapters/mysqlconnector/driver.py +38 -0
  21. sqlspec/adapters/oracledb/_storage.py +20 -102
  22. sqlspec/adapters/oracledb/adk/store.py +339 -177
  23. sqlspec/adapters/oracledb/core.py +31 -23
  24. sqlspec/adapters/oracledb/data_dictionary.py +2 -107
  25. sqlspec/adapters/oracledb/events/store.py +1 -15
  26. sqlspec/adapters/oracledb/litestar/store.py +1 -15
  27. sqlspec/adapters/psqlpy/adk/store.py +166 -65
  28. sqlspec/adapters/psqlpy/core.py +16 -16
  29. sqlspec/adapters/psycopg/adk/store.py +552 -195
  30. sqlspec/adapters/psycopg/core.py +17 -17
  31. sqlspec/adapters/psycopg/driver.py +41 -0
  32. sqlspec/adapters/pymssql/adk/store.py +147 -61
  33. sqlspec/adapters/pymysql/adk/store.py +169 -75
  34. sqlspec/adapters/pymysql/driver.py +36 -0
  35. sqlspec/adapters/spanner/adk/store.py +196 -99
  36. sqlspec/adapters/sqlite/adk/store.py +173 -102
  37. sqlspec/config.py +23 -20
  38. sqlspec/data_dictionary/dialects/oracle/sql/version.sql +0 -6
  39. sqlspec/driver/_async.py +105 -58
  40. sqlspec/driver/_common.py +9 -1
  41. sqlspec/driver/_exception_handler.py +43 -3
  42. sqlspec/driver/_sync.py +5 -1
  43. sqlspec/extensions/adk/__init__.py +40 -38
  44. sqlspec/extensions/adk/_config_utils.py +29 -7
  45. sqlspec/extensions/adk/_types.py +7 -4
  46. sqlspec/extensions/adk/artifact/__init__.py +3 -3
  47. sqlspec/extensions/adk/artifact/_types.py +2 -2
  48. sqlspec/extensions/adk/artifact/service.py +64 -18
  49. sqlspec/extensions/adk/artifact/store.py +55 -9
  50. sqlspec/extensions/adk/converters.py +15 -9
  51. sqlspec/extensions/adk/maintenance.py +259 -0
  52. sqlspec/extensions/adk/memory/__init__.py +3 -36
  53. sqlspec/extensions/adk/memory/_types.py +8 -3
  54. sqlspec/extensions/adk/memory/converters.py +55 -20
  55. sqlspec/extensions/adk/memory/service.py +53 -16
  56. sqlspec/extensions/adk/memory/store.py +199 -216
  57. sqlspec/extensions/adk/migrations/0001_create_adk_tables.py +150 -8
  58. sqlspec/extensions/adk/service.py +41 -3
  59. sqlspec/extensions/adk/store.py +132 -31
  60. sqlspec/extensions/events/__init__.py +11 -1
  61. sqlspec/extensions/events/_payload.py +47 -9
  62. sqlspec/extensions/litestar/plugin.py +73 -5
  63. sqlspec/utils/arrow_helpers.py +76 -15
  64. {sqlspec-0.60.0.dist-info → sqlspec-0.62.0.dist-info}/METADATA +2 -2
  65. {sqlspec-0.60.0.dist-info → sqlspec-0.62.0.dist-info}/RECORD +68 -68
  66. {sqlspec-0.60.0.dist-info → sqlspec-0.62.0.dist-info}/WHEEL +1 -1
  67. sqlspec/extensions/adk/migrations/0002_reset_adk_tables.py +0 -141
  68. {sqlspec-0.60.0.dist-info → sqlspec-0.62.0.dist-info}/entry_points.txt +0 -0
  69. {sqlspec-0.60.0.dist-info → sqlspec-0.62.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, normalize_session_list_options
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 SessionOrderBy, 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,21 +96,32 @@ 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(
100
+ self,
101
+ app_name: str,
102
+ user_id: "str | None" = None,
103
+ *,
104
+ order_by: "SessionOrderBy" = "update_time",
105
+ descending: bool = True,
106
+ limit: "int | None" = None,
107
+ offset: "int | None" = None,
108
+ ) -> "list[StoredSession]":
98
109
  """List sessions for an app."""
99
- return self._list_sessions(app_name, user_id)
110
+ return self._list_sessions(
111
+ app_name, user_id, order_by=order_by, descending=descending, limit=limit, offset=offset
112
+ )
100
113
 
101
114
  def delete_session(self, app_name: str, user_id: str, session_id: str) -> None:
102
115
  """Delete session and associated events."""
103
116
  self._delete_session(app_name, user_id, session_id)
104
117
 
105
- def append_event(self, event_record: EventRecord) -> None:
118
+ def append_event(self, event_record: StoredEvent) -> None:
106
119
  """Append an event to a session."""
107
120
  self._append_event(event_record)
108
121
 
109
122
  def append_event_and_update_state(
110
123
  self,
111
- event_record: EventRecord,
124
+ event_record: StoredEvent,
112
125
  app_name: str,
113
126
  user_id: str,
114
127
  session_id: str,
@@ -116,7 +129,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
116
129
  *,
117
130
  app_state: "dict[str, Any] | None" = None,
118
131
  user_state: "dict[str, Any] | None" = None,
119
- ) -> SessionRecord:
132
+ ) -> StoredSession:
120
133
  """Atomically append an event and update the session's durable state."""
121
134
  return self._append_event_and_update_state(
122
135
  event_record, app_name, user_id, session_id, state, app_state=app_state, user_state=user_state
@@ -129,17 +142,21 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
129
142
  session_id: str,
130
143
  after_timestamp: "datetime | None" = None,
131
144
  limit: "int | None" = None,
132
- ) -> "list[EventRecord]":
145
+ ) -> "list[StoredEvent]":
133
146
  """Get events for a session."""
134
147
  return self._get_events(app_name, user_id, session_id, after_timestamp, limit)
135
148
 
136
- def delete_expired_events(self, before: datetime) -> int:
149
+ def delete_expired_events(self, before: datetime, app_name: "str | None" = None) -> int:
137
150
  """Delete events older than a timestamp."""
138
- return self._delete_expired_events(before)
151
+ return self._delete_expired_events(before, app_name)
139
152
 
140
- def delete_idle_sessions(self, updated_before: datetime) -> int:
153
+ def delete_idle_sessions(self, updated_before: datetime, app_name: "str | None" = None) -> int:
141
154
  """Delete sessions older than a timestamp."""
142
- return self._delete_idle_sessions(updated_before)
155
+ return self._delete_idle_sessions(updated_before, app_name)
156
+
157
+ def delete_idle_user_states(self, updated_before: datetime, app_name: "str | None" = None) -> int:
158
+ """Delete user state rows older than a timestamp."""
159
+ return self._delete_idle_user_states(updated_before, app_name)
143
160
 
144
161
  def get_app_state(self, app_name: str) -> "dict[str, Any] | None":
145
162
  """Return app-scoped state."""
@@ -390,6 +407,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
390
407
  return f"""
391
408
  CREATE TABLE IF NOT EXISTS {self._events_table} (
392
409
  id VARCHAR(128) PRIMARY KEY,
410
+ app_name VARCHAR(128) NOT NULL,
411
+ user_id VARCHAR(128) NOT NULL,
393
412
  session_id VARCHAR(128) NOT NULL,
394
413
  invocation_id VARCHAR(256),
395
414
  timestamp TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -407,6 +426,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
407
426
  return f"""
408
427
  CREATE TABLE IF NOT EXISTS {self._events_table} (
409
428
  id TEXT PRIMARY KEY,
429
+ app_name TEXT NOT NULL,
430
+ user_id TEXT NOT NULL,
410
431
  session_id TEXT NOT NULL,
411
432
  invocation_id TEXT,
412
433
  timestamp REAL NOT NULL,
@@ -424,6 +445,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
424
445
  return f"""
425
446
  CREATE TABLE IF NOT EXISTS {self._events_table} (
426
447
  id VARCHAR(128) PRIMARY KEY,
448
+ app_name VARCHAR(128) NOT NULL,
449
+ user_id VARCHAR(128) NOT NULL,
427
450
  session_id VARCHAR(128) NOT NULL,
428
451
  invocation_id VARCHAR(256),
429
452
  timestamp TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -441,6 +464,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
441
464
  return f"""
442
465
  CREATE TABLE IF NOT EXISTS {self._events_table} (
443
466
  id VARCHAR PRIMARY KEY,
467
+ app_name VARCHAR NOT NULL,
468
+ user_id VARCHAR NOT NULL,
444
469
  session_id VARCHAR NOT NULL,
445
470
  invocation_id VARCHAR,
446
471
  timestamp TIMESTAMP_TZ NOT NULL DEFAULT CURRENT_TIMESTAMP(),
@@ -458,6 +483,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
458
483
  return f"""
459
484
  CREATE TABLE IF NOT EXISTS {self._events_table} (
460
485
  id VARCHAR(128) PRIMARY KEY,
486
+ app_name VARCHAR(128) NOT NULL,
487
+ user_id VARCHAR(128) NOT NULL,
461
488
  session_id VARCHAR(128) NOT NULL,
462
489
  invocation_id VARCHAR(256),
463
490
  timestamp TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -591,6 +618,33 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
591
618
  """Execute parameterized SQL using the current ADBC dialect's placeholder style."""
592
619
  return cursor.execute(self._format_sql(sql), params)
593
620
 
621
+ def _session_list_query(
622
+ self, app_name: str, user_id: "str | None", column: str, direction: str, limit: "int | None", offset: int
623
+ ) -> "tuple[str, tuple[Any, ...]]":
624
+ """Return the bounded session-list query in the current dialect's page grammar."""
625
+ params: list[Any] = [app_name]
626
+ where_clause = "app_name = ?"
627
+ if user_id is not None:
628
+ params.append(user_id)
629
+ where_clause = f"{where_clause} AND user_id = ?"
630
+
631
+ page_clause = ""
632
+ if limit is not None:
633
+ if self._dialect == DIALECT_GENERIC:
634
+ params.extend((offset, limit))
635
+ page_clause = "\n OFFSET ? ROWS FETCH NEXT ? ROWS ONLY"
636
+ else:
637
+ params.extend((limit, offset))
638
+ page_clause = "\n LIMIT ? OFFSET ?"
639
+
640
+ sql = f"""
641
+ SELECT id, app_name, user_id, state, create_time, update_time
642
+ FROM {self._session_table}
643
+ WHERE {where_clause}
644
+ ORDER BY {column} {direction}, id {direction}{page_clause}
645
+ """
646
+ return sql, tuple(params)
647
+
594
648
  def _json_placeholder(self) -> str:
595
649
  """Return a JSON parameter placeholder for the current dialect."""
596
650
  if self._dialect == DIALECT_POSTGRESQL:
@@ -599,7 +653,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
599
653
 
600
654
  def _create_session(
601
655
  self, session_id: str, app_name: str, user_id: str, state: "dict[str, Any]", owner_id: "Any | None" = None
602
- ) -> SessionRecord:
656
+ ) -> StoredSession:
603
657
  """Create a new session.
604
658
 
605
659
  Args:
@@ -646,7 +700,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
646
700
 
647
701
  def _get_session(
648
702
  self, app_name: str, user_id: str, session_id: str, *, renew_for: "int | timedelta | None" = None
649
- ) -> "SessionRecord | None":
703
+ ) -> "StoredSession | None":
650
704
  """Get session by ID.
651
705
 
652
706
  Args:
@@ -696,7 +750,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
696
750
  if row is None:
697
751
  return None
698
752
 
699
- return SessionRecord(
753
+ return StoredSession(
700
754
  id=row[0],
701
755
  app_name=row[1],
702
756
  user_id=row[2],
@@ -759,32 +813,34 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
759
813
  finally:
760
814
  cursor.close()
761
815
 
762
- def _list_sessions(self, app_name: str, user_id: str | None = None) -> "list[SessionRecord]":
816
+ def _list_sessions(
817
+ self,
818
+ app_name: str,
819
+ user_id: "str | None" = None,
820
+ *,
821
+ order_by: "SessionOrderBy" = "update_time",
822
+ descending: bool = True,
823
+ limit: "int | None" = None,
824
+ offset: "int | None" = None,
825
+ ) -> "list[StoredSession]":
763
826
  """List sessions for an app, optionally filtered by user.
764
827
 
765
828
  Args:
766
829
  app_name: Application name.
767
830
  user_id: User identifier. If None, lists all sessions for the app.
831
+ order_by: Timestamp column to sort on.
832
+ descending: Sort direction for the timestamp column and the id tie-break.
833
+ limit: Maximum number of sessions to return.
834
+ offset: Number of leading rows to skip.
768
835
 
769
836
  Returns:
770
- List of session records ordered by update_time DESC.
837
+ List of session records.
771
838
  """
772
- if user_id is None:
773
- sql = f"""
774
- SELECT id, app_name, user_id, state, create_time, update_time
775
- FROM {self._session_table}
776
- WHERE app_name = ?
777
- ORDER BY update_time DESC
778
- """
779
- params: tuple[str, ...] = (app_name,)
780
- else:
781
- sql = f"""
782
- SELECT id, app_name, user_id, state, create_time, update_time
783
- FROM {self._session_table}
784
- WHERE app_name = ? AND user_id = ?
785
- ORDER BY update_time DESC
786
- """
787
- params = (app_name, user_id)
839
+ column, direction, page_limit, page_offset = normalize_session_list_options(order_by, descending, limit, offset)
840
+ if page_limit == 0:
841
+ return []
842
+
843
+ sql, params = self._session_list_query(app_name, user_id, column, direction, page_limit, page_offset)
788
844
 
789
845
  try:
790
846
  with self._config.provide_connection() as conn:
@@ -794,7 +850,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
794
850
  rows = cursor.fetchall()
795
851
 
796
852
  return [
797
- SessionRecord(
853
+ StoredSession(
798
854
  id=row[0],
799
855
  app_name=row[1],
800
856
  user_id=row[2],
@@ -812,7 +868,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
812
868
  return []
813
869
  raise
814
870
 
815
- def _insert_event(self, event_record: "EventRecord") -> None:
871
+ def _insert_event(self, event_record: "StoredEvent") -> None:
816
872
  """Insert an event record into the events table.
817
873
 
818
874
  Args:
@@ -821,8 +877,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
821
877
  event_data = self._serialize_json_field(event_record["event_data"])
822
878
  sql = f"""
823
879
  INSERT INTO {self._events_table} (
824
- id, session_id, invocation_id, timestamp, event_data
825
- ) VALUES (?, ?, ?, ?, {self._json_placeholder()})
880
+ id, app_name, user_id, session_id, invocation_id, timestamp, event_data
881
+ ) VALUES (?, ?, ?, ?, ?, ?, {self._json_placeholder()})
826
882
  """
827
883
 
828
884
  with self._config.provide_connection() as conn:
@@ -833,6 +889,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
833
889
  sql,
834
890
  (
835
891
  event_record["id"],
892
+ event_record["app_name"],
893
+ event_record["user_id"],
836
894
  event_record["session_id"],
837
895
  event_record["invocation_id"],
838
896
  event_record["timestamp"],
@@ -845,7 +903,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
845
903
 
846
904
  def _append_event_and_update_state(
847
905
  self,
848
- event_record: "EventRecord",
906
+ event_record: "StoredEvent",
849
907
  app_name: str,
850
908
  user_id: str,
851
909
  session_id: str,
@@ -853,7 +911,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
853
911
  *,
854
912
  app_state: "dict[str, Any] | None" = None,
855
913
  user_state: "dict[str, Any] | None" = None,
856
- ) -> SessionRecord:
914
+ ) -> StoredSession:
857
915
  """Atomically insert an event and update the session's durable state.
858
916
 
859
917
  The event insert, state update, and refresh-SELECT are executed within
@@ -874,8 +932,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
874
932
  """
875
933
  insert_sql = f"""
876
934
  INSERT INTO {self._events_table} (
877
- id, session_id, invocation_id, timestamp, event_data
878
- ) VALUES (?, ?, ?, ?, {self._json_placeholder()})
935
+ id, app_name, user_id, session_id, invocation_id, timestamp, event_data
936
+ ) VALUES (?, ?, ?, ?, ?, ?, {self._json_placeholder()})
879
937
  """
880
938
  update_sql = f"""
881
939
  UPDATE {self._session_table}
@@ -908,6 +966,8 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
908
966
  insert_sql,
909
967
  (
910
968
  event_record["id"],
969
+ event_record["app_name"],
970
+ event_record["user_id"],
911
971
  event_record["session_id"],
912
972
  event_record["invocation_id"],
913
973
  event_record["timestamp"],
@@ -943,7 +1003,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
943
1003
  msg = f"Session {session_id} not found during append_event_and_update_state."
944
1004
  raise ValueError(msg)
945
1005
 
946
- return SessionRecord(
1006
+ return StoredSession(
947
1007
  id=row[0],
948
1008
  app_name=row[1],
949
1009
  user_id=row[2],
@@ -959,7 +1019,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
959
1019
  session_id: str,
960
1020
  after_timestamp: "datetime | None" = None,
961
1021
  limit: "int | None" = None,
962
- ) -> "list[EventRecord]":
1022
+ ) -> "list[StoredEvent]":
963
1023
  """List events for a session ordered by timestamp.
964
1024
 
965
1025
  Args:
@@ -1000,7 +1060,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
1000
1060
  rows = cursor.fetchall()
1001
1061
 
1002
1062
  return [
1003
- EventRecord(
1063
+ StoredEvent(
1004
1064
  id=row[0],
1005
1065
  session_id=row[1],
1006
1066
  invocation_id=row[2] or "",
@@ -1019,18 +1079,23 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
1019
1079
  return []
1020
1080
  raise
1021
1081
 
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 < ?"
1082
+ def _delete_expired_events(self, before: datetime, app_name: "str | None" = None) -> int:
1083
+ where = "WHERE timestamp < ?"
1084
+ params: tuple[Any, ...] = (before,)
1085
+ if app_name is not None:
1086
+ where += " AND app_name = ?"
1087
+ params = (before, app_name)
1088
+ count_sql = f"SELECT COUNT(*) FROM {self._events_table} {where}"
1089
+ delete_sql = f"DELETE FROM {self._events_table} {where}"
1025
1090
 
1026
1091
  try:
1027
1092
  with self._config.provide_connection() as conn:
1028
1093
  cursor = conn.cursor()
1029
1094
  try:
1030
- self._execute(cursor, count_sql, (before,))
1095
+ self._execute(cursor, count_sql, params)
1031
1096
  row = cursor.fetchone()
1032
1097
  count = int(row[0]) if row is not None else 0
1033
- self._execute(cursor, delete_sql, (before,))
1098
+ self._execute(cursor, delete_sql, params)
1034
1099
  conn.commit()
1035
1100
  return count
1036
1101
  finally:
@@ -1041,23 +1106,55 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
1041
1106
  return 0
1042
1107
  raise
1043
1108
 
1044
- def _delete_idle_sessions(self, updated_before: datetime) -> int:
1045
- count_sql = f"SELECT COUNT(*) FROM {self._session_table} WHERE update_time < ?"
1109
+ def _delete_idle_sessions(self, updated_before: datetime, app_name: "str | None" = None) -> int:
1110
+ where = "WHERE update_time < ?"
1111
+ params: tuple[Any, ...] = (updated_before,)
1112
+ if app_name is not None:
1113
+ where += " AND app_name = ?"
1114
+ params = (updated_before, app_name)
1115
+ count_sql = f"SELECT COUNT(*) FROM {self._session_table} {where}"
1046
1116
  delete_events_sql = f"""
1047
1117
  DELETE FROM {self._events_table}
1048
- WHERE session_id IN (SELECT id FROM {self._session_table} WHERE update_time < ?)
1118
+ WHERE session_id IN (SELECT id FROM {self._session_table} {where})
1049
1119
  """
1050
- delete_sessions_sql = f"DELETE FROM {self._session_table} WHERE update_time < ?"
1120
+ delete_sessions_sql = f"DELETE FROM {self._session_table} {where}"
1121
+
1122
+ try:
1123
+ with self._config.provide_connection() as conn:
1124
+ cursor = conn.cursor()
1125
+ try:
1126
+ self._execute(cursor, count_sql, params)
1127
+ row = cursor.fetchone()
1128
+ count = int(row[0]) if row is not None else 0
1129
+ self._execute(cursor, delete_events_sql, params)
1130
+ self._execute(cursor, delete_sessions_sql, params)
1131
+ conn.commit()
1132
+ return count
1133
+ finally:
1134
+ cursor.close()
1135
+ except Exception as exc:
1136
+ error_msg = str(exc).lower()
1137
+ if any(pattern in error_msg for pattern in ADBC_TABLE_NOT_FOUND_PATTERNS):
1138
+ return 0
1139
+ raise
1140
+
1141
+ def _delete_idle_user_states(self, updated_before: datetime, app_name: "str | None" = None) -> int:
1142
+ where = "WHERE update_time < ?"
1143
+ params: tuple[Any, ...] = (updated_before,)
1144
+ if app_name is not None:
1145
+ where += " AND app_name = ?"
1146
+ params = (updated_before, app_name)
1147
+ count_sql = f"SELECT COUNT(*) FROM {self._user_state_table} {where}"
1148
+ delete_sql = f"DELETE FROM {self._user_state_table} {where}"
1051
1149
 
1052
1150
  try:
1053
1151
  with self._config.provide_connection() as conn:
1054
1152
  cursor = conn.cursor()
1055
1153
  try:
1056
- self._execute(cursor, count_sql, (updated_before,))
1154
+ self._execute(cursor, count_sql, params)
1057
1155
  row = cursor.fetchone()
1058
1156
  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,))
1157
+ self._execute(cursor, delete_sql, params)
1061
1158
  conn.commit()
1062
1159
  return count
1063
1160
  finally:
@@ -1160,7 +1257,7 @@ class AdbcADKStore(BaseSyncADKStore["AdbcConfig"]):
1160
1257
  finally:
1161
1258
  cursor.close()
1162
1259
 
1163
- def _append_event(self, event_record: EventRecord) -> None:
1260
+ def _append_event(self, event_record: StoredEvent) -> None:
1164
1261
  """Synchronous implementation of append_event."""
1165
1262
  self._insert_event(event_record)
1166
1263
 
@@ -1186,23 +1283,29 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1186
1283
 
1187
1284
  self._create_tables()
1188
1285
 
1189
- def insert_memory_entries(self, entries: "list[MemoryRecord]", owner_id: "object | None" = None) -> int:
1286
+ def insert_memory_entries(self, entries: "list[StoredMemory]", owner_id: "object | None" = None) -> int:
1190
1287
  """Bulk insert memory entries with deduplication."""
1191
1288
  return self._insert_memory_entries(entries, owner_id)
1192
1289
 
1193
1290
  def search_entries(
1194
- self, query: str, app_name: str, user_id: str, limit: "int | None" = None
1195
- ) -> "list[MemoryRecord]":
1291
+ self,
1292
+ query: str,
1293
+ app_name: str,
1294
+ user_id: str,
1295
+ limit: "int | None" = None,
1296
+ scope_filter: Literal["all", "user", "app"] = "all",
1297
+ embedding: "Sequence[float] | None" = None,
1298
+ ) -> "list[StoredMemory]":
1196
1299
  """Search memory entries by text query."""
1197
- return self._search_entries(query, app_name, user_id, limit)
1300
+ return self._search_entries(query, app_name, user_id, limit, scope_filter)
1198
1301
 
1199
1302
  def delete_entries_by_session(self, session_id: str) -> int:
1200
1303
  """Delete all memory entries for a specific session."""
1201
1304
  return self._delete_entries_by_session(session_id)
1202
1305
 
1203
- def delete_entries_older_than(self, days: int) -> int:
1306
+ def delete_entries_older_than(self, days: int, app_name: "str | None" = None, scope: "str | None" = None) -> int:
1204
1307
  """Delete memory entries older than specified days."""
1205
- return self._delete_entries_older_than(days)
1308
+ return self._delete_entries_older_than(days, app_name, scope)
1206
1309
 
1207
1310
  def _detect_dialect(self) -> str:
1208
1311
  driver_name = self._config.connection_config.get("driver_name", "").lower()
@@ -1255,6 +1358,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1255
1358
  session_id VARCHAR(128) NOT NULL,
1256
1359
  app_name VARCHAR(128) NOT NULL,
1257
1360
  user_id VARCHAR(128) NOT NULL,
1361
+ scope VARCHAR(16) NOT NULL DEFAULT 'user',
1258
1362
  event_id VARCHAR(128) NOT NULL UNIQUE,
1259
1363
  author VARCHAR(256){owner_id_ddl},
1260
1364
  timestamp TIMESTAMPTZ NOT NULL,
@@ -1273,6 +1377,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1273
1377
  session_id TEXT NOT NULL,
1274
1378
  app_name TEXT NOT NULL,
1275
1379
  user_id TEXT NOT NULL,
1380
+ scope TEXT NOT NULL DEFAULT 'user',
1276
1381
  event_id TEXT NOT NULL UNIQUE,
1277
1382
  author TEXT{owner_id_ddl},
1278
1383
  timestamp REAL NOT NULL,
@@ -1291,6 +1396,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1291
1396
  session_id VARCHAR(128) NOT NULL,
1292
1397
  app_name VARCHAR(128) NOT NULL,
1293
1398
  user_id VARCHAR(128) NOT NULL,
1399
+ scope VARCHAR(16) NOT NULL DEFAULT 'user',
1294
1400
  event_id VARCHAR(128) NOT NULL UNIQUE,
1295
1401
  author VARCHAR(256){owner_id_ddl},
1296
1402
  timestamp TIMESTAMP NOT NULL,
@@ -1309,6 +1415,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1309
1415
  session_id VARCHAR NOT NULL,
1310
1416
  app_name VARCHAR NOT NULL,
1311
1417
  user_id VARCHAR NOT NULL,
1418
+ scope VARCHAR NOT NULL DEFAULT 'user',
1312
1419
  event_id VARCHAR NOT NULL UNIQUE,
1313
1420
  author VARCHAR{owner_id_ddl},
1314
1421
  timestamp TIMESTAMP_TZ NOT NULL,
@@ -1327,6 +1434,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1327
1434
  session_id VARCHAR(128) NOT NULL,
1328
1435
  app_name VARCHAR(128) NOT NULL,
1329
1436
  user_id VARCHAR(128) NOT NULL,
1437
+ scope VARCHAR(16) NOT NULL DEFAULT 'user',
1330
1438
  event_id VARCHAR(128) NOT NULL UNIQUE,
1331
1439
  author VARCHAR(256){owner_id_ddl},
1332
1440
  timestamp TIMESTAMP NOT NULL,
@@ -1350,8 +1458,12 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1350
1458
  cursor.execute(self._memory_table_ddl())
1351
1459
  conn.commit()
1352
1460
 
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)
1461
+ 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)"
1462
+ cursor.execute(idx_app_scope_user)
1463
+ conn.commit()
1464
+
1465
+ idx_scope = f"CREATE INDEX IF NOT EXISTS idx_{self._memory_table}_scope ON {self._memory_table}(app_name, scope)"
1466
+ cursor.execute(idx_scope)
1355
1467
  conn.commit()
1356
1468
 
1357
1469
  idx_session = (
@@ -1362,7 +1474,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1362
1474
  finally:
1363
1475
  cursor.close()
1364
1476
 
1365
- def _insert_memory_entries(self, entries: "list[MemoryRecord]", owner_id: "object | None" = None) -> int:
1477
+ def _insert_memory_entries(self, entries: "list[StoredMemory]", owner_id: "object | None" = None) -> int:
1366
1478
  if not self._enabled:
1367
1479
  msg = "Memory store is disabled"
1368
1480
  raise RuntimeError(msg)
@@ -1377,39 +1489,39 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1377
1489
  if use_returning:
1378
1490
  sql = f"""
1379
1491
  INSERT INTO {self._memory_table} (
1380
- id, session_id, app_name, user_id, event_id, author,
1492
+ id, session_id, app_name, user_id, scope, event_id, author,
1381
1493
  {self._owner_id_column_name}, timestamp, content_json, content_text,
1382
1494
  metadata_json, inserted_at
1383
1495
  ) VALUES (
1384
- ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1496
+ ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1385
1497
  ) ON CONFLICT(event_id) DO NOTHING RETURNING 1
1386
1498
  """
1387
1499
  else:
1388
1500
  sql = f"""
1389
1501
  INSERT INTO {self._memory_table} (
1390
- id, session_id, app_name, user_id, event_id, author,
1502
+ id, session_id, app_name, user_id, scope, event_id, author,
1391
1503
  {self._owner_id_column_name}, timestamp, content_json, content_text,
1392
1504
  metadata_json, inserted_at
1393
1505
  ) VALUES (
1394
- ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1506
+ ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1395
1507
  )
1396
1508
  """
1397
1509
  elif use_returning:
1398
1510
  sql = f"""
1399
1511
  INSERT INTO {self._memory_table} (
1400
- id, session_id, app_name, user_id, event_id, author,
1512
+ id, session_id, app_name, user_id, scope, event_id, author,
1401
1513
  timestamp, content_json, content_text, metadata_json, inserted_at
1402
1514
  ) VALUES (
1403
- ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1515
+ ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1404
1516
  ) ON CONFLICT(event_id) DO NOTHING RETURNING 1
1405
1517
  """
1406
1518
  else:
1407
1519
  sql = f"""
1408
1520
  INSERT INTO {self._memory_table} (
1409
- id, session_id, app_name, user_id, event_id, author,
1521
+ id, session_id, app_name, user_id, scope, event_id, author,
1410
1522
  timestamp, content_json, content_text, metadata_json, inserted_at
1411
1523
  ) VALUES (
1412
- ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1524
+ ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
1413
1525
  )
1414
1526
  """
1415
1527
 
@@ -1426,6 +1538,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1426
1538
  entry["session_id"],
1427
1539
  entry["app_name"],
1428
1540
  entry["user_id"],
1541
+ entry.get("scope", "user"),
1429
1542
  entry["event_id"],
1430
1543
  entry["author"],
1431
1544
  owner_id,
@@ -1441,6 +1554,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1441
1554
  entry["session_id"],
1442
1555
  entry["app_name"],
1443
1556
  entry["user_id"],
1557
+ entry.get("scope", "user"),
1444
1558
  entry["event_id"],
1445
1559
  entry["author"],
1446
1560
  self._encode_timestamp(entry["timestamp"]),
@@ -1469,8 +1583,13 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1469
1583
  return inserted_count
1470
1584
 
1471
1585
  def _search_entries(
1472
- self, query: str, app_name: str, user_id: str, limit: "int | None" = None
1473
- ) -> "list[MemoryRecord]":
1586
+ self,
1587
+ query: str,
1588
+ app_name: str,
1589
+ user_id: str,
1590
+ limit: "int | None" = None,
1591
+ scope_filter: Literal["all", "user", "app"] = "all",
1592
+ ) -> "list[StoredMemory]":
1474
1593
  if not self._enabled:
1475
1594
  msg = "Memory store is disabled"
1476
1595
  raise RuntimeError(msg)
@@ -1480,13 +1599,13 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1480
1599
 
1481
1600
  effective_limit = limit if limit is not None else self._max_results
1482
1601
  pattern = f"%{query}%"
1602
+ where_scope, scope_params = _build_adbc_scope_where(app_name, user_id, scope_filter)
1483
1603
 
1484
1604
  sql = f"""
1485
- SELECT id, session_id, app_name, user_id, event_id, author,
1605
+ SELECT id, session_id, app_name, user_id, scope, event_id, author,
1486
1606
  timestamp, content_json, content_text, metadata_json, inserted_at
1487
1607
  FROM {self._memory_table}
1488
- WHERE app_name = ?
1489
- AND user_id = ?
1608
+ WHERE {where_scope}
1490
1609
  AND content_text LIKE ?
1491
1610
  ORDER BY timestamp DESC
1492
1611
  LIMIT ?
@@ -1496,7 +1615,7 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1496
1615
  with self._config.provide_connection() as conn:
1497
1616
  cursor = conn.cursor()
1498
1617
  try:
1499
- cursor.execute(sql, (app_name, user_id, pattern, effective_limit))
1618
+ cursor.execute(sql, (*scope_params, pattern, effective_limit))
1500
1619
  rows = cursor.fetchall()
1501
1620
  finally:
1502
1621
  cursor.close()
@@ -1527,17 +1646,26 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1527
1646
  finally:
1528
1647
  cursor.close()
1529
1648
 
1530
- def _delete_entries_older_than(self, days: int) -> int:
1649
+ def _delete_entries_older_than(self, days: int, app_name: "str | None" = None, scope: "str | None" = None) -> int:
1531
1650
  cutoff = self._encode_timestamp(datetime.now(timezone.utc) - timedelta(days=days))
1532
1651
  use_returning = self._dialect in {DIALECT_SQLITE, DIALECT_POSTGRESQL, DIALECT_DUCKDB}
1652
+ clauses = ["inserted_at < ?"]
1653
+ params: list[Any] = [cutoff]
1654
+ if app_name is not None:
1655
+ clauses.append("app_name = ?")
1656
+ params.append(app_name)
1657
+ if scope is not None:
1658
+ clauses.append("scope = ?")
1659
+ params.append(scope)
1660
+ where_sql = " AND ".join(clauses)
1533
1661
  if use_returning:
1534
- sql = f"DELETE FROM {self._memory_table} WHERE inserted_at < ? RETURNING 1"
1662
+ sql = f"DELETE FROM {self._memory_table} WHERE {where_sql} RETURNING 1"
1535
1663
  else:
1536
- sql = f"DELETE FROM {self._memory_table} WHERE inserted_at < ?"
1664
+ sql = f"DELETE FROM {self._memory_table} WHERE {where_sql}"
1537
1665
  with self._config.provide_connection() as conn:
1538
1666
  cursor = conn.cursor()
1539
1667
  try:
1540
- cursor.execute(sql, (cutoff,))
1668
+ cursor.execute(sql, tuple(params))
1541
1669
  if use_returning:
1542
1670
  deleted_rows = cursor.fetchall()
1543
1671
  conn.commit()
@@ -1547,16 +1675,16 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1547
1675
  finally:
1548
1676
  cursor.close()
1549
1677
 
1550
- def _rows_to_records(self, rows: "list[Any]") -> "list[MemoryRecord]":
1551
- records: list[MemoryRecord] = []
1678
+ def _rows_to_records(self, rows: "list[Any]") -> "list[StoredMemory]":
1679
+ records: list[StoredMemory] = []
1552
1680
  for row in rows:
1553
- content_json = row[7]
1681
+ content_json = row[8]
1554
1682
  if isinstance(content_json, dict):
1555
1683
  content_value = content_json
1556
1684
  else:
1557
1685
  content_value = from_json(content_json if isinstance(content_json, (str, bytes)) else str(content_json))
1558
1686
 
1559
- metadata_json = row[9]
1687
+ metadata_json = row[10]
1560
1688
  if metadata_json is None:
1561
1689
  metadata_value = None
1562
1690
  elif isinstance(metadata_json, dict):
@@ -1571,12 +1699,24 @@ class AdbcADKMemoryStore(BaseSyncADKMemoryStore["AdbcConfig"]):
1571
1699
  "session_id": row[1],
1572
1700
  "app_name": row[2],
1573
1701
  "user_id": row[3],
1574
- "event_id": row[4],
1575
- "author": row[5],
1576
- "timestamp": self._decode_timestamp(row[6]),
1702
+ "scope": row[4],
1703
+ "event_id": row[5],
1704
+ "author": row[6],
1705
+ "timestamp": self._decode_timestamp(row[7]),
1577
1706
  "content_json": content_value,
1578
- "content_text": row[8],
1707
+ "content_text": row[9],
1579
1708
  "metadata_json": metadata_value,
1580
- "inserted_at": self._decode_timestamp(row[10]),
1709
+ "inserted_at": self._decode_timestamp(row[11]),
1710
+ "embedding": None,
1581
1711
  })
1582
1712
  return records
1713
+
1714
+
1715
+ def _build_adbc_scope_where(
1716
+ app_name: str, user_id: str, scope_filter: Literal["all", "user", "app"]
1717
+ ) -> tuple[str, tuple[Any, ...]]:
1718
+ if scope_filter == "all":
1719
+ return "app_name = ? AND ((scope = 'user' AND user_id = ?) OR scope = 'app')", (app_name, user_id)
1720
+ if scope_filter == "user":
1721
+ return "app_name = ? AND scope = 'user' AND user_id = ?", (app_name, user_id)
1722
+ return "app_name = ? AND scope = 'app'", (app_name,)