open-memory-lab-sdk 0.8.3__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 (521) hide show
  1. oml_sdk/__init__.py +63 -0
  2. oml_sdk/client.py +733 -0
  3. oml_sdk/errors.py +231 -0
  4. oml_sdk/generated/__init__.py +8 -0
  5. oml_sdk/generated/api/__init__.py +1 -0
  6. oml_sdk/generated/api/account/__init__.py +1 -0
  7. oml_sdk/generated/api/account/get_account_usage.py +226 -0
  8. oml_sdk/generated/api/admin/__init__.py +1 -0
  9. oml_sdk/generated/api/admin/admin_account_usage.py +230 -0
  10. oml_sdk/generated/api/admin/admin_read_memory.py +234 -0
  11. oml_sdk/generated/api/admin/admin_rescan.py +256 -0
  12. oml_sdk/generated/api/admin/admin_rescan_record_held.py +272 -0
  13. oml_sdk/generated/api/admin/admin_search_memories.py +243 -0
  14. oml_sdk/generated/api/admin/admin_usage_drift.py +217 -0
  15. oml_sdk/generated/api/admin/admin_usage_ledger.py +274 -0
  16. oml_sdk/generated/api/admin/clear_account_profile.py +242 -0
  17. oml_sdk/generated/api/admin/set_account_profile.py +265 -0
  18. oml_sdk/generated/api/crews/__init__.py +1 -0
  19. oml_sdk/generated/api/crews/create_crew.py +243 -0
  20. oml_sdk/generated/api/crews/get_crew.py +221 -0
  21. oml_sdk/generated/api/crews/list_crews.py +235 -0
  22. oml_sdk/generated/api/crews/update_crew.py +267 -0
  23. oml_sdk/generated/api/edges/__init__.py +1 -0
  24. oml_sdk/generated/api/edges/list_edges.py +290 -0
  25. oml_sdk/generated/api/edges/propose_edge.py +235 -0
  26. oml_sdk/generated/api/edges/ratify_edge.py +229 -0
  27. oml_sdk/generated/api/events/__init__.py +1 -0
  28. oml_sdk/generated/api/events/tail_events.py +312 -0
  29. oml_sdk/generated/api/health/__init__.py +1 -0
  30. oml_sdk/generated/api/health/healthz.py +189 -0
  31. oml_sdk/generated/api/health/readyz.py +194 -0
  32. oml_sdk/generated/api/imports/__init__.py +1 -0
  33. oml_sdk/generated/api/imports/get_import.py +229 -0
  34. oml_sdk/generated/api/imports/import_bundle.py +370 -0
  35. oml_sdk/generated/api/keys/__init__.py +1 -0
  36. oml_sdk/generated/api/keys/add_denial.py +318 -0
  37. oml_sdk/generated/api/keys/bootstrap_claim.py +248 -0
  38. oml_sdk/generated/api/keys/get_key.py +221 -0
  39. oml_sdk/generated/api/keys/issue_key.py +379 -0
  40. oml_sdk/generated/api/keys/link_key.py +332 -0
  41. oml_sdk/generated/api/keys/list_keys.py +280 -0
  42. oml_sdk/generated/api/keys/mint_connect_code.py +328 -0
  43. oml_sdk/generated/api/keys/revoke_connection.py +287 -0
  44. oml_sdk/generated/api/keys/set_key_limits.py +308 -0
  45. oml_sdk/generated/api/keys/unlink_key.py +269 -0
  46. oml_sdk/generated/api/keys/whoami.py +288 -0
  47. oml_sdk/generated/api/memories/__init__.py +1 -0
  48. oml_sdk/generated/api/memories/get_guardrails.py +268 -0
  49. oml_sdk/generated/api/memories/get_memory.py +299 -0
  50. oml_sdk/generated/api/memories/get_skills.py +287 -0
  51. oml_sdk/generated/api/memories/list_memories.py +623 -0
  52. oml_sdk/generated/api/memories/preview_memory.py +281 -0
  53. oml_sdk/generated/api/memories/recall_memories.py +284 -0
  54. oml_sdk/generated/api/memories/source_check_memory.py +300 -0
  55. oml_sdk/generated/api/memories/submit_memory.py +321 -0
  56. oml_sdk/generated/api/memories/supersede_memory.py +371 -0
  57. oml_sdk/generated/api/memories/withdraw_memory.py +302 -0
  58. oml_sdk/generated/api/oauth/__init__.py +1 -0
  59. oml_sdk/generated/api/oauth/authorization_server_metadata.py +205 -0
  60. oml_sdk/generated/api/oauth/authorize.py +392 -0
  61. oml_sdk/generated/api/oauth/authorize_submit.py +285 -0
  62. oml_sdk/generated/api/oauth/protected_resource_metadata.py +209 -0
  63. oml_sdk/generated/api/oauth/register_client.py +250 -0
  64. oml_sdk/generated/api/oauth/token.py +290 -0
  65. oml_sdk/generated/api/review/__init__.py +1 -0
  66. oml_sdk/generated/api/review/admin_todo_counts.py +217 -0
  67. oml_sdk/generated/api/review/post_bulk_verdict.py +300 -0
  68. oml_sdk/generated/api/review/post_verdict.py +333 -0
  69. oml_sdk/generated/api/review/review_held.py +399 -0
  70. oml_sdk/generated/api/review/review_next.py +293 -0
  71. oml_sdk/generated/api/review/review_queue.py +229 -0
  72. oml_sdk/generated/api/review/todo_counts.py +257 -0
  73. oml_sdk/generated/api/search/__init__.py +1 -0
  74. oml_sdk/generated/api/search/federation_settings.py +205 -0
  75. oml_sdk/generated/api/search/search_settings.py +201 -0
  76. oml_sdk/generated/api/search/set_federation_policy.py +246 -0
  77. oml_sdk/generated/api/search/set_search_default.py +242 -0
  78. oml_sdk/generated/api/uploads/__init__.py +1 -0
  79. oml_sdk/generated/api/uploads/abandon_upload.py +232 -0
  80. oml_sdk/generated/api/uploads/complete_upload.py +257 -0
  81. oml_sdk/generated/api/uploads/get_upload.py +225 -0
  82. oml_sdk/generated/api/uploads/open_upload.py +276 -0
  83. oml_sdk/generated/api/uploads/put_upload_part.py +300 -0
  84. oml_sdk/generated/api/usage/__init__.py +1 -0
  85. oml_sdk/generated/api/usage/set_usage_settings.py +246 -0
  86. oml_sdk/generated/api/usage/usage_eval.py +247 -0
  87. oml_sdk/generated/api/usage/usage_events.py +252 -0
  88. oml_sdk/generated/api/usage/usage_settings.py +201 -0
  89. oml_sdk/generated/api/web/__init__.py +1 -0
  90. oml_sdk/generated/api/web/allow_web_email.py +264 -0
  91. oml_sdk/generated/api/web/close_web_deletion.py +283 -0
  92. oml_sdk/generated/api/web/disable_web_user.py +304 -0
  93. oml_sdk/generated/api/web/end_web_session.py +215 -0
  94. oml_sdk/generated/api/web/export_web_person.py +213 -0
  95. oml_sdk/generated/api/web/grant_web_capacities.py +295 -0
  96. oml_sdk/generated/api/web/list_web_emails.py +244 -0
  97. oml_sdk/generated/api/web/list_web_users.py +213 -0
  98. oml_sdk/generated/api/web/remove_web_email.py +247 -0
  99. oml_sdk/generated/api/web/request_web_deletion.py +244 -0
  100. oml_sdk/generated/api/web/set_web_user_quota.py +287 -0
  101. oml_sdk/generated/api/web/user_page.py +162 -0
  102. oml_sdk/generated/api/web/user_page_act.py +181 -0
  103. oml_sdk/generated/api/web/web_callback.py +230 -0
  104. oml_sdk/generated/api/web/web_sign_in.py +173 -0
  105. oml_sdk/generated/api/web/web_sign_in_page.py +182 -0
  106. oml_sdk/generated/api/web/web_sign_up.py +189 -0
  107. oml_sdk/generated/api/workspaces/__init__.py +1 -0
  108. oml_sdk/generated/api/workspaces/create_workspace.py +275 -0
  109. oml_sdk/generated/api/workspaces/export_workspace.py +307 -0
  110. oml_sdk/generated/api/workspaces/get_workspace.py +273 -0
  111. oml_sdk/generated/api/workspaces/get_workspace_offers.py +261 -0
  112. oml_sdk/generated/api/workspaces/get_workspace_tree.py +322 -0
  113. oml_sdk/generated/api/workspaces/propose_transition.py +239 -0
  114. oml_sdk/generated/api/workspaces/ratify_transition.py +234 -0
  115. oml_sdk/generated/api/workspaces/set_workspace_crew.py +282 -0
  116. oml_sdk/generated/api/workspaces/set_workspace_federation.py +292 -0
  117. oml_sdk/generated/api/workspaces/set_workspace_mode.py +306 -0
  118. oml_sdk/generated/client.py +280 -0
  119. oml_sdk/generated/errors.py +16 -0
  120. oml_sdk/generated/models/__init__.py +837 -0
  121. oml_sdk/generated/models/account_profile_request.py +71 -0
  122. oml_sdk/generated/models/account_profile_request_overrides.py +50 -0
  123. oml_sdk/generated/models/account_usage.py +110 -0
  124. oml_sdk/generated/models/account_usage_meters_item.py +89 -0
  125. oml_sdk/generated/models/account_usage_meters_item_meter.py +13 -0
  126. oml_sdk/generated/models/account_usage_meters_item_state.py +10 -0
  127. oml_sdk/generated/models/admin_memory.py +376 -0
  128. oml_sdk/generated/models/admin_memory_kind.py +17 -0
  129. oml_sdk/generated/models/admin_memory_state.py +13 -0
  130. oml_sdk/generated/models/admin_read_memory_response_200.py +444 -0
  131. oml_sdk/generated/models/admin_read_memory_response_200_verdicts_item.py +127 -0
  132. oml_sdk/generated/models/admin_search_memories_body.py +140 -0
  133. oml_sdk/generated/models/admin_search_memories_body_origin_kind.py +14 -0
  134. oml_sdk/generated/models/admin_search_memories_body_state.py +13 -0
  135. oml_sdk/generated/models/admin_search_memories_response_200.py +89 -0
  136. oml_sdk/generated/models/admin_todo_counts_response_200.py +61 -0
  137. oml_sdk/generated/models/admin_usage_ledger_format.py +9 -0
  138. oml_sdk/generated/models/allow_web_email_body.py +71 -0
  139. oml_sdk/generated/models/anchor.py +125 -0
  140. oml_sdk/generated/models/anchor_hasher.py +14 -0
  141. oml_sdk/generated/models/approver.py +65 -0
  142. oml_sdk/generated/models/approver_used_by.py +10 -0
  143. oml_sdk/generated/models/attachment_descriptor.py +79 -0
  144. oml_sdk/generated/models/authorization_server_metadata.py +289 -0
  145. oml_sdk/generated/models/authorization_server_metadata_code_challenge_methods_supported_item.py +8 -0
  146. oml_sdk/generated/models/authorization_server_metadata_grant_types_supported_item.py +9 -0
  147. oml_sdk/generated/models/authorization_server_metadata_response_types_supported_item.py +8 -0
  148. oml_sdk/generated/models/authorization_server_metadata_scopes_supported_item.py +8 -0
  149. oml_sdk/generated/models/authorization_server_metadata_token_endpoint_auth_methods_supported_item.py +8 -0
  150. oml_sdk/generated/models/authorize_code_challenge_method.py +8 -0
  151. oml_sdk/generated/models/authorize_response_type.py +8 -0
  152. oml_sdk/generated/models/authorize_scope.py +8 -0
  153. oml_sdk/generated/models/authorize_submit_body_type_0.py +51 -0
  154. oml_sdk/generated/models/authorize_submit_body_type_1.py +53 -0
  155. oml_sdk/generated/models/authorize_submit_body_type_1_action.py +9 -0
  156. oml_sdk/generated/models/bootstrap_claim_body.py +54 -0
  157. oml_sdk/generated/models/brief.py +71 -0
  158. oml_sdk/generated/models/brief_edge.py +135 -0
  159. oml_sdk/generated/models/brief_edge_proposal.py +74 -0
  160. oml_sdk/generated/models/brief_edge_state.py +9 -0
  161. oml_sdk/generated/models/build.py +94 -0
  162. oml_sdk/generated/models/build_profile.py +10 -0
  163. oml_sdk/generated/models/bulk_verdict_request.py +71 -0
  164. oml_sdk/generated/models/bulk_verdict_request_verdict.py +9 -0
  165. oml_sdk/generated/models/bulk_verdict_result.py +85 -0
  166. oml_sdk/generated/models/bulk_verdict_result_items_item.py +194 -0
  167. oml_sdk/generated/models/bulk_verdict_result_items_item_details_type_0.py +45 -0
  168. oml_sdk/generated/models/bulk_verdict_result_items_item_outcome.py +10 -0
  169. oml_sdk/generated/models/bulk_verdict_result_items_item_state.py +9 -0
  170. oml_sdk/generated/models/bulk_verdict_result_summary.py +77 -0
  171. oml_sdk/generated/models/catalog_count_type_1.py +42 -0
  172. oml_sdk/generated/models/claim_edge.py +133 -0
  173. oml_sdk/generated/models/claim_edge_proposal.py +75 -0
  174. oml_sdk/generated/models/claim_edge_state.py +9 -0
  175. oml_sdk/generated/models/claim_kind.py +17 -0
  176. oml_sdk/generated/models/client_registration.py +169 -0
  177. oml_sdk/generated/models/client_registration_request.py +153 -0
  178. oml_sdk/generated/models/client_registration_request_grant_types_item.py +9 -0
  179. oml_sdk/generated/models/client_registration_request_response_types_item.py +8 -0
  180. oml_sdk/generated/models/client_registration_request_token_endpoint_auth_method.py +8 -0
  181. oml_sdk/generated/models/close_web_deletion_body.py +44 -0
  182. oml_sdk/generated/models/close_web_deletion_body_outcome.py +8 -0
  183. oml_sdk/generated/models/close_web_deletion_response_200.py +61 -0
  184. oml_sdk/generated/models/connect_code.py +91 -0
  185. oml_sdk/generated/models/connection.py +187 -0
  186. oml_sdk/generated/models/connection_client_kind.py +9 -0
  187. oml_sdk/generated/models/connection_revoked_cause_type_1.py +11 -0
  188. oml_sdk/generated/models/connection_revoked_cause_type_2_type_1.py +11 -0
  189. oml_sdk/generated/models/connection_revoked_cause_type_3_type_1.py +11 -0
  190. oml_sdk/generated/models/connection_state.py +9 -0
  191. oml_sdk/generated/models/crew.py +130 -0
  192. oml_sdk/generated/models/crew_create.py +66 -0
  193. oml_sdk/generated/models/crew_page.py +89 -0
  194. oml_sdk/generated/models/crew_update.py +52 -0
  195. oml_sdk/generated/models/denial.py +88 -0
  196. oml_sdk/generated/models/denial_request.py +62 -0
  197. oml_sdk/generated/models/disable_web_user_body.py +23 -0
  198. oml_sdk/generated/models/disable_web_user_response_200.py +69 -0
  199. oml_sdk/generated/models/document_fields.py +44 -0
  200. oml_sdk/generated/models/edge_page.py +114 -0
  201. oml_sdk/generated/models/error_code.py +107 -0
  202. oml_sdk/generated/models/error_envelope.py +75 -0
  203. oml_sdk/generated/models/error_envelope_error.py +114 -0
  204. oml_sdk/generated/models/error_envelope_error_details.py +45 -0
  205. oml_sdk/generated/models/events_page.py +92 -0
  206. oml_sdk/generated/models/export_request.py +80 -0
  207. oml_sdk/generated/models/export_request_mode.py +9 -0
  208. oml_sdk/generated/models/export_web_person_response_200.py +145 -0
  209. oml_sdk/generated/models/export_web_person_response_200_keys_item.py +45 -0
  210. oml_sdk/generated/models/export_web_person_response_200_memories_item.py +45 -0
  211. oml_sdk/generated/models/federation_settings.py +106 -0
  212. oml_sdk/generated/models/federation_settings_default_sources.py +9 -0
  213. oml_sdk/generated/models/federation_settings_wide_keys_item.py +51 -0
  214. oml_sdk/generated/models/federation_settings_widen_signal.py +84 -0
  215. oml_sdk/generated/models/feedback.py +92 -0
  216. oml_sdk/generated/models/grant.py +133 -0
  217. oml_sdk/generated/models/grant_covers.py +9 -0
  218. oml_sdk/generated/models/grant_deny_item.py +61 -0
  219. oml_sdk/generated/models/grant_request.py +110 -0
  220. oml_sdk/generated/models/grant_request_covers.py +9 -0
  221. oml_sdk/generated/models/grant_request_deny_item.py +51 -0
  222. oml_sdk/generated/models/grant_request_role.py +10 -0
  223. oml_sdk/generated/models/grant_role.py +10 -0
  224. oml_sdk/generated/models/grant_web_capacities_body.py +52 -0
  225. oml_sdk/generated/models/grant_web_capacities_body_capacity.py +9 -0
  226. oml_sdk/generated/models/grant_web_capacities_response_200.py +103 -0
  227. oml_sdk/generated/models/grant_web_capacities_response_200_key.py +76 -0
  228. oml_sdk/generated/models/guardrail_rule.py +124 -0
  229. oml_sdk/generated/models/guardrail_rule_effect.py +9 -0
  230. oml_sdk/generated/models/guardrail_rule_rule.py +8 -0
  231. oml_sdk/generated/models/guardrail_rule_tool.py +12 -0
  232. oml_sdk/generated/models/guardrail_scope.py +9 -0
  233. oml_sdk/generated/models/guardrail_set.py +124 -0
  234. oml_sdk/generated/models/guardrail_set_own_held_item.py +50 -0
  235. oml_sdk/generated/models/health.py +69 -0
  236. oml_sdk/generated/models/held_named.py +76 -0
  237. oml_sdk/generated/models/held_named_items_item.py +105 -0
  238. oml_sdk/generated/models/held_page.py +139 -0
  239. oml_sdk/generated/models/held_page_items_item.py +954 -0
  240. oml_sdk/generated/models/held_page_lane_authors_type_0_item.py +70 -0
  241. oml_sdk/generated/models/import_.py +174 -0
  242. oml_sdk/generated/models/import_answer.py +49 -0
  243. oml_sdk/generated/models/import_counts.py +50 -0
  244. oml_sdk/generated/models/import_plan.py +149 -0
  245. oml_sdk/generated/models/import_plan_counts.py +45 -0
  246. oml_sdk/generated/models/import_plan_edges.py +50 -0
  247. oml_sdk/generated/models/import_plan_keys_item.py +105 -0
  248. oml_sdk/generated/models/import_plan_keys_item_outcome.py +13 -0
  249. oml_sdk/generated/models/import_plan_keys_item_source_type_0.py +50 -0
  250. oml_sdk/generated/models/import_plan_source.py +58 -0
  251. oml_sdk/generated/models/import_refusals_item.py +64 -0
  252. oml_sdk/generated/models/import_refusals_item_source.py +50 -0
  253. oml_sdk/generated/models/import_request.py +111 -0
  254. oml_sdk/generated/models/import_source.py +50 -0
  255. oml_sdk/generated/models/import_state.py +10 -0
  256. oml_sdk/generated/models/import_status.py +48 -0
  257. oml_sdk/generated/models/journal_event.py +180 -0
  258. oml_sdk/generated/models/journal_event_payload.py +45 -0
  259. oml_sdk/generated/models/key.py +567 -0
  260. oml_sdk/generated/models/key_credential.py +10 -0
  261. oml_sdk/generated/models/key_issue_request.py +256 -0
  262. oml_sdk/generated/models/key_issue_request_profile.py +8 -0
  263. oml_sdk/generated/models/key_issue_request_used_by.py +10 -0
  264. oml_sdk/generated/models/key_issued.py +594 -0
  265. oml_sdk/generated/models/key_limits.py +105 -0
  266. oml_sdk/generated/models/key_limits_request.py +89 -0
  267. oml_sdk/generated/models/key_link.py +71 -0
  268. oml_sdk/generated/models/key_link_request.py +42 -0
  269. oml_sdk/generated/models/key_live_connect_code_type_1.py +78 -0
  270. oml_sdk/generated/models/key_profile_type_1.py +8 -0
  271. oml_sdk/generated/models/key_profile_type_2_type_1.py +8 -0
  272. oml_sdk/generated/models/key_profile_type_3_type_1.py +8 -0
  273. oml_sdk/generated/models/key_used_by_type_1.py +10 -0
  274. oml_sdk/generated/models/key_used_by_type_2_type_1.py +10 -0
  275. oml_sdk/generated/models/key_used_by_type_3_type_1.py +10 -0
  276. oml_sdk/generated/models/list_edges_kind.py +9 -0
  277. oml_sdk/generated/models/list_keys_response_200.py +89 -0
  278. oml_sdk/generated/models/list_web_emails_response_200.py +89 -0
  279. oml_sdk/generated/models/list_web_users_response_200.py +117 -0
  280. oml_sdk/generated/models/list_web_users_response_200_deletions_item.py +70 -0
  281. oml_sdk/generated/models/list_web_users_response_200_mode.py +9 -0
  282. oml_sdk/generated/models/listed_key.py +213 -0
  283. oml_sdk/generated/models/listed_key_credential.py +10 -0
  284. oml_sdk/generated/models/listed_key_grants_item.py +80 -0
  285. oml_sdk/generated/models/listed_key_used_by.py +10 -0
  286. oml_sdk/generated/models/memory.py +923 -0
  287. oml_sdk/generated/models/memory_page.py +110 -0
  288. oml_sdk/generated/models/memory_page_counts.py +83 -0
  289. oml_sdk/generated/models/memory_preview.py +251 -0
  290. oml_sdk/generated/models/memory_preview_passages_item.py +93 -0
  291. oml_sdk/generated/models/memory_preview_refusal_type_0.py +118 -0
  292. oml_sdk/generated/models/memory_preview_refusal_type_0_details.py +45 -0
  293. oml_sdk/generated/models/memory_preview_rule.py +47 -0
  294. oml_sdk/generated/models/memory_preview_set_after.py +71 -0
  295. oml_sdk/generated/models/memory_preview_shadows_item.py +73 -0
  296. oml_sdk/generated/models/memory_preview_shadows_item_relation.py +9 -0
  297. oml_sdk/generated/models/memory_summary.py +814 -0
  298. oml_sdk/generated/models/memory_summary_kind.py +17 -0
  299. oml_sdk/generated/models/memory_summary_provenance.py +11 -0
  300. oml_sdk/generated/models/memory_summary_replaces_type_0.py +73 -0
  301. oml_sdk/generated/models/memory_summary_severity.py +10 -0
  302. oml_sdk/generated/models/memory_summary_state.py +13 -0
  303. oml_sdk/generated/models/mint_connect_code_body.py +45 -0
  304. oml_sdk/generated/models/o_auth_error.py +75 -0
  305. oml_sdk/generated/models/o_auth_error_error.py +15 -0
  306. oml_sdk/generated/models/origin.py +47 -0
  307. oml_sdk/generated/models/origin_kind.py +14 -0
  308. oml_sdk/generated/models/postings_health.py +119 -0
  309. oml_sdk/generated/models/preview_supersede_request.py +363 -0
  310. oml_sdk/generated/models/protected_resource_metadata.py +140 -0
  311. oml_sdk/generated/models/protected_resource_metadata_bearer_methods_supported_item.py +8 -0
  312. oml_sdk/generated/models/protected_resource_metadata_scopes_supported_item.py +8 -0
  313. oml_sdk/generated/models/ready.py +158 -0
  314. oml_sdk/generated/models/ready_checks.py +47 -0
  315. oml_sdk/generated/models/ready_scan_type_0.py +82 -0
  316. oml_sdk/generated/models/ready_status.py +9 -0
  317. oml_sdk/generated/models/ready_web_client.py +11 -0
  318. oml_sdk/generated/models/recall_budget.py +105 -0
  319. oml_sdk/generated/models/recall_budget_counter.py +8 -0
  320. oml_sdk/generated/models/recall_event.py +156 -0
  321. oml_sdk/generated/models/recall_event_access.py +10 -0
  322. oml_sdk/generated/models/recall_event_hits_item.py +51 -0
  323. oml_sdk/generated/models/recall_event_labels_item.py +88 -0
  324. oml_sdk/generated/models/recall_event_labels_item_label.py +14 -0
  325. oml_sdk/generated/models/recall_event_labels_item_source.py +9 -0
  326. oml_sdk/generated/models/recall_matched.py +153 -0
  327. oml_sdk/generated/models/recall_matched_tokens_item.py +58 -0
  328. oml_sdk/generated/models/recall_matched_via_item.py +14 -0
  329. oml_sdk/generated/models/recall_passage.py +96 -0
  330. oml_sdk/generated/models/recall_request.py +360 -0
  331. oml_sdk/generated/models/recall_request_match.py +9 -0
  332. oml_sdk/generated/models/recall_request_search.py +17 -0
  333. oml_sdk/generated/models/recall_request_sources_type_0.py +9 -0
  334. oml_sdk/generated/models/recall_response.py +186 -0
  335. oml_sdk/generated/models/recall_response_hits_item.py +148 -0
  336. oml_sdk/generated/models/recall_response_hits_item_via.py +9 -0
  337. oml_sdk/generated/models/recall_response_steering_type_1.py +8 -0
  338. oml_sdk/generated/models/recall_search.py +297 -0
  339. oml_sdk/generated/models/recall_search_access.py +9 -0
  340. oml_sdk/generated/models/recall_search_hits.py +8 -0
  341. oml_sdk/generated/models/recall_search_match.py +9 -0
  342. oml_sdk/generated/models/recall_search_matched_by_kind.py +50 -0
  343. oml_sdk/generated/models/recall_search_pipeline.py +17 -0
  344. oml_sdk/generated/models/recall_search_widen.py +65 -0
  345. oml_sdk/generated/models/recall_search_widen_sources.py +8 -0
  346. oml_sdk/generated/models/recall_search_window_type_0.py +96 -0
  347. oml_sdk/generated/models/recall_sources.py +89 -0
  348. oml_sdk/generated/models/recall_sources_cut.py +52 -0
  349. oml_sdk/generated/models/recall_sources_mode.py +9 -0
  350. oml_sdk/generated/models/recall_sources_searched_item.py +88 -0
  351. oml_sdk/generated/models/recall_sources_searched_item_matched.py +42 -0
  352. oml_sdk/generated/models/recall_sources_searched_item_via.py +9 -0
  353. oml_sdk/generated/models/recall_timings.py +60 -0
  354. oml_sdk/generated/models/recall_timings_stages_ms.py +50 -0
  355. oml_sdk/generated/models/remove_web_email_body.py +55 -0
  356. oml_sdk/generated/models/remove_web_email_response_200.py +78 -0
  357. oml_sdk/generated/models/replay_report.py +90 -0
  358. oml_sdk/generated/models/replay_report_pipelines_item.py +82 -0
  359. oml_sdk/generated/models/request_web_deletion_response_200.py +88 -0
  360. oml_sdk/generated/models/rerank_outcome.py +9 -0
  361. oml_sdk/generated/models/rerank_reason.py +10 -0
  362. oml_sdk/generated/models/rescan_report.py +202 -0
  363. oml_sdk/generated/models/rescan_report_by_rule_item.py +68 -0
  364. oml_sdk/generated/models/rescan_report_by_rule_item_action.py +9 -0
  365. oml_sdk/generated/models/rescan_report_findings_item.py +132 -0
  366. oml_sdk/generated/models/rescan_report_findings_item_action.py +9 -0
  367. oml_sdk/generated/models/rescan_report_scanned_by_origin.py +50 -0
  368. oml_sdk/generated/models/review_held_needs.py +9 -0
  369. oml_sdk/generated/models/review_next_body.py +76 -0
  370. oml_sdk/generated/models/review_next_body_needs.py +9 -0
  371. oml_sdk/generated/models/review_policy.py +73 -0
  372. oml_sdk/generated/models/review_queue_response_200.py +79 -0
  373. oml_sdk/generated/models/review_queue_response_200_items_item.py +107 -0
  374. oml_sdk/generated/models/revoke_connection_body.py +42 -0
  375. oml_sdk/generated/models/role.py +12 -0
  376. oml_sdk/generated/models/scan_finding.py +183 -0
  377. oml_sdk/generated/models/scan_finding_found_by.py +9 -0
  378. oml_sdk/generated/models/scan_finding_verdict.py +10 -0
  379. oml_sdk/generated/models/search_settings.py +129 -0
  380. oml_sdk/generated/models/search_settings_valid_time.py +64 -0
  381. oml_sdk/generated/models/serve.py +113 -0
  382. oml_sdk/generated/models/served_digests.py +81 -0
  383. oml_sdk/generated/models/served_guardrail.py +269 -0
  384. oml_sdk/generated/models/served_guardrail_effect_inside_type_1.py +8 -0
  385. oml_sdk/generated/models/served_guardrail_effect_inside_type_2_type_1.py +8 -0
  386. oml_sdk/generated/models/served_guardrail_effect_inside_type_3_type_1.py +8 -0
  387. oml_sdk/generated/models/served_guardrail_verdicts_item.py +55 -0
  388. oml_sdk/generated/models/served_guardrail_verdicts_item_used_by.py +10 -0
  389. oml_sdk/generated/models/served_skill.py +175 -0
  390. oml_sdk/generated/models/set_federation_policy_body.py +70 -0
  391. oml_sdk/generated/models/set_federation_policy_body_default_sources.py +9 -0
  392. oml_sdk/generated/models/set_search_default_body.py +54 -0
  393. oml_sdk/generated/models/set_usage_settings_body.py +42 -0
  394. oml_sdk/generated/models/set_web_user_quota_body.py +116 -0
  395. oml_sdk/generated/models/set_workspace_federation_body.py +42 -0
  396. oml_sdk/generated/models/set_workspace_federation_response_200.py +42 -0
  397. oml_sdk/generated/models/severity.py +10 -0
  398. oml_sdk/generated/models/similar_item.py +113 -0
  399. oml_sdk/generated/models/similar_item_kind.py +10 -0
  400. oml_sdk/generated/models/similar_item_relation.py +9 -0
  401. oml_sdk/generated/models/similar_item_state.py +9 -0
  402. oml_sdk/generated/models/skill_fields.py +52 -0
  403. oml_sdk/generated/models/skill_set.py +108 -0
  404. oml_sdk/generated/models/source_check_request.py +80 -0
  405. oml_sdk/generated/models/source_check_request_result.py +12 -0
  406. oml_sdk/generated/models/source_check_result.py +110 -0
  407. oml_sdk/generated/models/source_checked.py +95 -0
  408. oml_sdk/generated/models/source_checked_moved_to_type_0.py +56 -0
  409. oml_sdk/generated/models/source_checked_result.py +12 -0
  410. oml_sdk/generated/models/stale.py +9 -0
  411. oml_sdk/generated/models/submit_accepted.py +209 -0
  412. oml_sdk/generated/models/submit_accepted_replaces_type_0.py +71 -0
  413. oml_sdk/generated/models/submit_accepted_scan.py +70 -0
  414. oml_sdk/generated/models/submit_request.py +365 -0
  415. oml_sdk/generated/models/submit_request_kind.py +17 -0
  416. oml_sdk/generated/models/submit_request_on_similar.py +9 -0
  417. oml_sdk/generated/models/submit_request_verb.py +9 -0
  418. oml_sdk/generated/models/supersede_request.py +338 -0
  419. oml_sdk/generated/models/supersede_request_kind.py +17 -0
  420. oml_sdk/generated/models/supersede_request_on_similar.py +9 -0
  421. oml_sdk/generated/models/test_fields.py +45 -0
  422. oml_sdk/generated/models/test_fields_shape.py +11 -0
  423. oml_sdk/generated/models/todo_counts_response_200.py +70 -0
  424. oml_sdk/generated/models/token_request.py +136 -0
  425. oml_sdk/generated/models/token_request_grant_type.py +9 -0
  426. oml_sdk/generated/models/token_request_scope.py +8 -0
  427. oml_sdk/generated/models/token_response.py +97 -0
  428. oml_sdk/generated/models/token_response_scope.py +8 -0
  429. oml_sdk/generated/models/token_response_token_type.py +8 -0
  430. oml_sdk/generated/models/transition.py +127 -0
  431. oml_sdk/generated/models/transition_from.py +9 -0
  432. oml_sdk/generated/models/transition_proposal.py +46 -0
  433. oml_sdk/generated/models/transition_proposal_to.py +9 -0
  434. oml_sdk/generated/models/transition_state.py +9 -0
  435. oml_sdk/generated/models/transition_to.py +9 -0
  436. oml_sdk/generated/models/upload_open_request.py +61 -0
  437. oml_sdk/generated/models/upload_open_request_purpose.py +8 -0
  438. oml_sdk/generated/models/upload_session.py +147 -0
  439. oml_sdk/generated/models/upload_session_purpose.py +8 -0
  440. oml_sdk/generated/models/upload_session_state.py +13 -0
  441. oml_sdk/generated/models/usage_drift.py +80 -0
  442. oml_sdk/generated/models/usage_drift_drift_item.py +82 -0
  443. oml_sdk/generated/models/usage_drift_drift_item_meter.py +12 -0
  444. oml_sdk/generated/models/usage_drift_undeclared_profiles_item.py +64 -0
  445. oml_sdk/generated/models/usage_eval_body.py +42 -0
  446. oml_sdk/generated/models/usage_events_response_200.py +70 -0
  447. oml_sdk/generated/models/usage_ledger.py +64 -0
  448. oml_sdk/generated/models/usage_ledger_rows_item.py +128 -0
  449. oml_sdk/generated/models/usage_settings.py +72 -0
  450. oml_sdk/generated/models/user_page_act_body.py +71 -0
  451. oml_sdk/generated/models/user_page_act_body_action.py +8 -0
  452. oml_sdk/generated/models/verdict_request.py +83 -0
  453. oml_sdk/generated/models/verdict_request_verdict.py +9 -0
  454. oml_sdk/generated/models/verdict_result.py +111 -0
  455. oml_sdk/generated/models/verdict_result_state.py +10 -0
  456. oml_sdk/generated/models/verdict_result_verdict.py +9 -0
  457. oml_sdk/generated/models/web_callback_provider.py +9 -0
  458. oml_sdk/generated/models/web_email.py +60 -0
  459. oml_sdk/generated/models/web_sign_in_body.py +55 -0
  460. oml_sdk/generated/models/web_sign_in_body_provider.py +9 -0
  461. oml_sdk/generated/models/web_sign_up_body.py +52 -0
  462. oml_sdk/generated/models/web_sign_up_body_accept_terms.py +8 -0
  463. oml_sdk/generated/models/web_user.py +125 -0
  464. oml_sdk/generated/models/web_user_quotas.py +128 -0
  465. oml_sdk/generated/models/web_user_usage.py +97 -0
  466. oml_sdk/generated/models/whoami.py +426 -0
  467. oml_sdk/generated/models/whoami_grant.py +88 -0
  468. oml_sdk/generated/models/whoami_grant_covers.py +9 -0
  469. oml_sdk/generated/models/whoami_grant_role.py +10 -0
  470. oml_sdk/generated/models/whoami_person.py +203 -0
  471. oml_sdk/generated/models/whoami_person_quotas_type_0.py +128 -0
  472. oml_sdk/generated/models/whoami_person_start_type_0.py +153 -0
  473. oml_sdk/generated/models/whoami_person_start_type_0_first_memory_type_1.py +9 -0
  474. oml_sdk/generated/models/whoami_person_start_type_0_first_memory_type_2_type_1.py +9 -0
  475. oml_sdk/generated/models/whoami_person_start_type_0_first_memory_type_3_type_1.py +9 -0
  476. oml_sdk/generated/models/whoami_person_usage_type_0.py +97 -0
  477. oml_sdk/generated/models/whoami_profile_type_1.py +8 -0
  478. oml_sdk/generated/models/whoami_profile_type_2_type_1.py +8 -0
  479. oml_sdk/generated/models/whoami_profile_type_3_type_1.py +8 -0
  480. oml_sdk/generated/models/whoami_ref.py +51 -0
  481. oml_sdk/generated/models/whoami_used_by.py +10 -0
  482. oml_sdk/generated/models/whoami_workspace.py +60 -0
  483. oml_sdk/generated/models/withdraw_request.py +42 -0
  484. oml_sdk/generated/models/withdraw_result.py +88 -0
  485. oml_sdk/generated/models/withdraw_result_state.py +8 -0
  486. oml_sdk/generated/models/workspace.py +187 -0
  487. oml_sdk/generated/models/workspace_counts.py +112 -0
  488. oml_sdk/generated/models/workspace_counts_items_item.py +147 -0
  489. oml_sdk/generated/models/workspace_counts_items_item_counts.py +85 -0
  490. oml_sdk/generated/models/workspace_counts_items_item_mode.py +9 -0
  491. oml_sdk/generated/models/workspace_create.py +89 -0
  492. oml_sdk/generated/models/workspace_crew_update.py +47 -0
  493. oml_sdk/generated/models/workspace_mode.py +9 -0
  494. oml_sdk/generated/models/workspace_mode_set.py +45 -0
  495. oml_sdk/generated/models/workspace_mode_set_mode.py +9 -0
  496. oml_sdk/generated/models/workspace_offers.py +173 -0
  497. oml_sdk/generated/models/workspace_offers_commit.py +75 -0
  498. oml_sdk/generated/models/workspace_offers_mode.py +9 -0
  499. oml_sdk/generated/models/workspace_offers_mode_change_type_0.py +72 -0
  500. oml_sdk/generated/models/workspace_offers_mode_change_type_0_to.py +8 -0
  501. oml_sdk/generated/models/workspace_offers_refused_item.py +88 -0
  502. oml_sdk/generated/models/workspace_offers_refused_item_op.py +9 -0
  503. oml_sdk/generated/models/workspace_offers_refused_item_to.py +11 -0
  504. oml_sdk/generated/models/workspace_offers_transitions_item.py +100 -0
  505. oml_sdk/generated/models/workspace_offers_transitions_item_op.py +9 -0
  506. oml_sdk/generated/models/workspace_page.py +89 -0
  507. oml_sdk/generated/models/workspace_status.py +10 -0
  508. oml_sdk/generated/models/workspace_view.py +379 -0
  509. oml_sdk/generated/models/workspace_view_approved_by_kind.py +51 -0
  510. oml_sdk/generated/models/workspace_view_children_item.py +60 -0
  511. oml_sdk/generated/models/workspace_view_children_item_status.py +10 -0
  512. oml_sdk/generated/models/workspace_view_edges_item.py +77 -0
  513. oml_sdk/generated/models/workspace_view_edges_item_label.py +11 -0
  514. oml_sdk/generated/models/workspace_view_edges_item_state.py +9 -0
  515. oml_sdk/generated/models/workspace_view_federation.py +44 -0
  516. oml_sdk/generated/models/workspace_view_my_effective_verbs_item.py +17 -0
  517. oml_sdk/generated/types.py +54 -0
  518. open_memory_lab_sdk-0.8.3.dist-info/METADATA +88 -0
  519. open_memory_lab_sdk-0.8.3.dist-info/RECORD +521 -0
  520. open_memory_lab_sdk-0.8.3.dist-info/WHEEL +4 -0
  521. open_memory_lab_sdk-0.8.3.dist-info/licenses/LICENSE +202 -0
oml_sdk/client.py ADDED
@@ -0,0 +1,733 @@
1
+ """The hand-written wrapper over the generated layer (docs/engineering/sdks.md).
2
+
3
+ It adds what a generator cannot know: where the URL and key come from, one
4
+ Idempotency-Key per write that every retry of the call reuses, cursor
5
+ iteration, the one error type every refusal raises, and the seven verbs of
6
+ ADR-0039 d10 — `write`, `read`, `workspace`, `events`, `review_next`, `approve`
7
+ and `reject` — whose fields choose the route as `oml_write`'s and `oml_read`'s
8
+ choose theirs. Every request still goes through a generated operation, with
9
+ generated models.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import dataclasses
15
+ import datetime
16
+ import importlib.metadata
17
+ import os
18
+ import time
19
+ import uuid
20
+ from collections.abc import Callable, Iterator, Mapping, Sequence
21
+ from typing import Any, Generic, Self, TypeVar
22
+
23
+ import httpx
24
+
25
+ from .errors import ApiError, ConfigError, TransportError, error_from_response, refused_locally
26
+ from .generated.api.events import tail_events
27
+ from .generated.api.keys import whoami
28
+ from .generated.api.memories import (
29
+ get_memory,
30
+ get_skills,
31
+ list_memories,
32
+ recall_memories,
33
+ submit_memory,
34
+ supersede_memory,
35
+ withdraw_memory,
36
+ )
37
+ from .generated.api.review import post_verdict, review_next
38
+ from .generated.api.workspaces import get_workspace
39
+ from .generated.client import Client
40
+ from .generated.models import (
41
+ Anchor,
42
+ ClaimKind,
43
+ DocumentFields,
44
+ EventsPage,
45
+ Memory,
46
+ MemoryPage,
47
+ MemorySummary,
48
+ Origin,
49
+ OriginKind,
50
+ RecallRequest,
51
+ RecallRequestMatch,
52
+ RecallRequestSearch,
53
+ RecallRequestSourcesType0,
54
+ RecallResponse,
55
+ Serve,
56
+ ServedSkill,
57
+ SkillFields,
58
+ SkillSet,
59
+ SubmitAccepted,
60
+ SubmitRequest,
61
+ SubmitRequestKind,
62
+ SupersedeRequest,
63
+ SupersedeRequestKind,
64
+ VerdictRequest,
65
+ VerdictRequestVerdict,
66
+ VerdictResult,
67
+ WithdrawRequest,
68
+ WithdrawResult,
69
+ WorkspaceView,
70
+ )
71
+ from .generated.types import UNSET, Response
72
+
73
+ T = TypeVar("T")
74
+
75
+ # What every request sends as User-Agent: the server's request log names the
76
+ # client by it (ADR-0042 d9).
77
+ USER_AGENT = f"oml-sdk-python/{importlib.metadata.version('open-memory-lab-sdk')}"
78
+
79
+ RETRY_AFTER_CAP = 30.0 # seconds; the most a Retry-After is waited for
80
+ FIRST_BACKOFF = 0.2 # seconds, doubling per attempt, when no Retry-After is sent
81
+
82
+ # The rules errors.md states for the two codes a refusal raised before sending
83
+ # carries, as the server's refusal of the same arguments would.
84
+ VALIDATION_RULE = "The contract is openapi.yaml; what it does not admit is refused, not coerced."
85
+ UNRESOLVED_RULE = (
86
+ "The target workspace comes from the request's workspace or, omitted, from the key's "
87
+ "default_workspace. A key with neither is refused, never guessed for."
88
+ )
89
+
90
+ # The arguments of `read`'s recall and listing modes: oml_read's (ADR-0039
91
+ # d4), and include_text, which the HTTP recall serves beside them.
92
+ READ_RECALL = (
93
+ "as_of",
94
+ "workspace",
95
+ "k",
96
+ "kinds",
97
+ "include_text",
98
+ "include_unreviewed",
99
+ "max_tokens",
100
+ "search",
101
+ "match",
102
+ "anchor_repo",
103
+ "anchor_path_prefix",
104
+ "origin_kinds",
105
+ "sources",
106
+ )
107
+ READ_LISTING = (
108
+ "as_of",
109
+ "own",
110
+ "workspace",
111
+ "claim_key",
112
+ "state",
113
+ "kinds",
114
+ "prefix",
115
+ "include_text",
116
+ "since",
117
+ "until",
118
+ "limit",
119
+ "cursor",
120
+ "anchor_repo",
121
+ "anchor_path_prefix",
122
+ "origin_kinds",
123
+ )
124
+
125
+
126
+ @dataclasses.dataclass(frozen=True)
127
+ class Written(Generic[T]):
128
+ """A write's result, the Idempotency-Key every attempt of it sent, and
129
+ whether the server answered with its stored response (Idempotency-Replay)."""
130
+
131
+ value: T
132
+ idempotency_key: str
133
+ replayed: bool
134
+
135
+
136
+ class _Bearer(httpx.Auth):
137
+ """Adds the key to each request and keeps it out of every repr."""
138
+
139
+ def __init__(self, key: str) -> None:
140
+ self.__key = key
141
+
142
+ def auth_flow(self, request: httpx.Request):
143
+ request.headers["Authorization"] = f"Bearer {self.__key}"
144
+ yield request
145
+
146
+ def __repr__(self) -> str:
147
+ return "_Bearer(<key withheld>)"
148
+
149
+
150
+ def _raise_for_refusal(response: httpx.Response) -> None:
151
+ """An httpx response hook: a non-2xx answer becomes its typed exception
152
+ before the generated layer parses it."""
153
+ if response.status_code >= 400:
154
+ response.read()
155
+ raise error_from_response(response.status_code, response.content, response.headers)
156
+
157
+
158
+ def _opt(value: Any) -> Any:
159
+ return UNSET if value is None else value
160
+
161
+
162
+ def _replayed(response: Response[Any]) -> bool:
163
+ return response.headers.get("idempotency-replay", "").lower() == "true"
164
+
165
+
166
+ def _invalid(field: str, message: str) -> ApiError:
167
+ """`request.validation` naming `field`, raised before anything is sent."""
168
+ return refused_locally(
169
+ 400, "request.validation", message, VALIDATION_RULE, {"field": f"/{field}"}
170
+ )
171
+
172
+
173
+ def _outside_mode(sent: Mapping[str, Any], allowed: Sequence[str], mode: str) -> None:
174
+ """Refuse, before sending, the first argument set outside `mode`'s."""
175
+ for field, value in sent.items():
176
+ if value is not None and field not in allowed:
177
+ raise _invalid(
178
+ field,
179
+ f"{field} is not an argument of read's {mode} mode: "
180
+ "artifact_id fetches, query recalls, and neither lists",
181
+ )
182
+
183
+
184
+ def _start_pair(url: str | None, api_key: str | None) -> tuple[str, str]:
185
+ """The URL-and-key pair from the first source that sets either value: the
186
+ arguments, then OML_URL and OML_API_KEY. A source setting one alone is
187
+ refused naming the other, so a key is never sent to a URL from another
188
+ source (ADR-0039 d15, the CLI's rule)."""
189
+ sources = (
190
+ ("url", "api_key", "passed", url or None, api_key or None),
191
+ ("OML_URL", "OML_API_KEY", "set", os.environ.get("OML_URL") or None,
192
+ os.environ.get("OML_API_KEY") or None),
193
+ ) # fmt: skip
194
+ for url_name, key_name, verb, found_url, found_key in sources:
195
+ if found_url and found_key:
196
+ return found_url, found_key
197
+ if found_url:
198
+ raise ConfigError(f"{url_name} is {verb} without {key_name}")
199
+ if found_key:
200
+ raise ConfigError(f"{key_name} is {verb} without {url_name}")
201
+ raise ConfigError("no URL and API key: pass url and api_key, or set OML_URL and OML_API_KEY")
202
+
203
+
204
+ def fence_for(format: str | None) -> str:
205
+ """The Markdown fence info string of a claim's media type, so a client
206
+ that renders fenced blocks can show a claim by its format: `mermaid`,
207
+ `json`, `yaml`, the `lang` of a code snippet, `markdown`, and the empty
208
+ string for plain text and for a media type this SDK does not know
209
+ (ADR-0056 d9).
210
+ """
211
+ media = (format or "text/plain").split(";")[0].strip()
212
+ if media == "text/markdown":
213
+ return "markdown"
214
+ if media == "text/vnd.oml.mermaid":
215
+ return "mermaid"
216
+ if media == "application/json":
217
+ return "json"
218
+ if media == "application/yaml":
219
+ return "yaml"
220
+ if media == "text/vnd.oml.code":
221
+ for part in (format or "").split(";")[1:]:
222
+ name, _, value = part.strip().partition("=")
223
+ if name == "lang" and value:
224
+ return value.strip()
225
+ return ""
226
+
227
+
228
+ class OmlClient:
229
+ """A client for one OML server under one key.
230
+
231
+ It starts from one pair: `url` and `api_key`, else `OML_URL` and
232
+ `OML_API_KEY`, taken from the first source that sets either. A source
233
+ setting one alone, or no source at all, raises `ConfigError` before
234
+ anything is sent (ADR-0039 d15).
235
+ """
236
+
237
+ def __init__(
238
+ self,
239
+ url: str | None = None,
240
+ api_key: str | None = None,
241
+ *,
242
+ retries: int = 2,
243
+ timeout: float = 10.0,
244
+ transport: httpx.BaseTransport | None = None,
245
+ ) -> None:
246
+ url, api_key = _start_pair(url, api_key)
247
+ if retries < 0:
248
+ raise ConfigError("retries must be 0 or more")
249
+ self._url = url.rstrip("/")
250
+ self._retries = retries
251
+ http = httpx.Client(
252
+ base_url=self._url,
253
+ auth=_Bearer(api_key),
254
+ headers={"User-Agent": USER_AGENT},
255
+ timeout=timeout,
256
+ transport=transport,
257
+ event_hooks={"response": [_raise_for_refusal]},
258
+ )
259
+ self._api = Client(base_url=self._url).set_httpx_client(http)
260
+
261
+ def __repr__(self) -> str:
262
+ return f"OmlClient(url={self._url!r})"
263
+
264
+ def close(self) -> None:
265
+ self._api.get_httpx_client().close()
266
+
267
+ def __enter__(self) -> Self:
268
+ return self
269
+
270
+ def __exit__(self, *exc: object) -> None:
271
+ self.close()
272
+
273
+ # -- the retry loop ---------------------------------------------------
274
+
275
+ def _send(self, call: Callable[[], Response[Any]]) -> Response[Any]:
276
+ """Send one call, retrying transport failures and retryable refusals.
277
+ The caller closes over everything the call sends, its
278
+ Idempotency-Key included, so every attempt sends the same request."""
279
+ attempt = 0
280
+ while True:
281
+ try:
282
+ return call()
283
+ except ApiError as refusal:
284
+ if not refusal.retryable or attempt >= self._retries:
285
+ raise
286
+ wait = refusal.retry_after
287
+ except httpx.TransportError as failure:
288
+ if attempt >= self._retries:
289
+ raise TransportError(f"the request failed in transit: {failure}") from failure
290
+ wait = None
291
+ time.sleep(
292
+ min(wait, RETRY_AFTER_CAP) if wait is not None else FIRST_BACKOFF * 2**attempt
293
+ )
294
+ attempt += 1
295
+
296
+ def _write(
297
+ self, idempotency_key: str | None, call: Callable[[str], Response[Any]]
298
+ ) -> Written[Any]:
299
+ key = idempotency_key or str(uuid.uuid4())
300
+ response = self._send(lambda: call(key))
301
+ return Written(value=response.parsed, idempotency_key=key, replayed=_replayed(response))
302
+
303
+ # -- the provider ring (/v1) --------------------------------------------
304
+
305
+ def write(
306
+ self,
307
+ text: str,
308
+ *,
309
+ claim_key: str | None = None,
310
+ kind: str | None = None,
311
+ derives_from: Sequence[str] | None = None,
312
+ workspace: str | None = None,
313
+ replaces: str | None = None,
314
+ expected_version: int | None = None,
315
+ retirement: bool | None = None,
316
+ reason: str | None = None,
317
+ anchor: Mapping[str, Any] | None = None,
318
+ format: str | None = None,
319
+ title: str | None = None,
320
+ origin_kind: str | None = None,
321
+ skill: Mapping[str, str] | None = None,
322
+ document: Mapping[str, str] | None = None,
323
+ idempotency_key: str | None = None,
324
+ ) -> Written[SubmitAccepted]:
325
+ """Write a claim, held on arrival; the fields set choose the route
326
+ (ADR-0039 d3). Without `replaces`, one `POST /v1/memories`, the
327
+ server deriving the verb from `derives_from` and, omitted, the kind
328
+ and the claim key. With `replaces`, a successor of that served tip,
329
+ or with `retirement=True` a proposal to retire it, `text` saying why.
330
+ `retirement` or `reason` without `replaces`, and `claim_key` with it,
331
+ raise `request.validation` naming the field before anything is sent.
332
+ With `replaces`, `expected_version` is required: the claim's latest
333
+ version as last read, else `submission.version_conflict` (ADR-0057
334
+ d19). `anchor` is the origin the author declares (ADR-0057 d1),
335
+ `origin_kind` what kind of source the text came from, recorded
336
+ `manual` when omitted (ADR-0063 d1, d2), `format` the media type of
337
+ `text`, `text/plain` when omitted, and `title` the one line a claim
338
+ that is not prose requires (ADR-0056). `skill`, `{"name",
339
+ "description"}`, is required on kind `skill` and refused on every
340
+ other kind (ADR-0080 d1); `document`, `{"title"}`, is optional on kind
341
+ `document` (ADR-0081 d1). A supersession of a skill or a document
342
+ sends them again, as every version carries its own.
343
+ """
344
+ skill_fields = SkillFields.from_dict(dict(skill)) if skill is not None else UNSET
345
+ document_fields = (
346
+ DocumentFields.from_dict(dict(document)) if document is not None else UNSET
347
+ )
348
+ if replaces is None:
349
+ for field, value in (
350
+ ("retirement", retirement),
351
+ ("reason", reason),
352
+ ("expected_version", expected_version),
353
+ ):
354
+ if value is not None:
355
+ raise _invalid(
356
+ field,
357
+ f"{field} is refused without replaces: it belongs to a supersession, "
358
+ "so pass replaces naming the version it changes",
359
+ )
360
+ submission = SubmitRequest(
361
+ body=text,
362
+ claim_key=_opt(claim_key),
363
+ kind=SubmitRequestKind(kind) if kind is not None else UNSET,
364
+ workspace=_opt(workspace),
365
+ derives_from=list(derives_from) if derives_from is not None else UNSET,
366
+ anchor=Anchor.from_dict(dict(anchor)) if anchor is not None else UNSET,
367
+ format_=_opt(format),
368
+ title=_opt(title),
369
+ origin=Origin(kind=OriginKind(origin_kind)) if origin_kind is not None else UNSET,
370
+ skill=skill_fields,
371
+ document=document_fields,
372
+ )
373
+ return self._write(
374
+ idempotency_key,
375
+ lambda key: submit_memory.sync_detailed(
376
+ client=self._api, body=submission, idempotency_key=key
377
+ ),
378
+ )
379
+ if claim_key is not None:
380
+ raise _invalid(
381
+ "claim_key",
382
+ "claim_key is refused with replaces: the new version takes its target's claim_key",
383
+ )
384
+ if expected_version is None:
385
+ raise _invalid(
386
+ "expected_version",
387
+ "expected_version is required with replaces: the claim's latest version as last "
388
+ "read, so a supersession never replaces a version it did not see",
389
+ )
390
+ successor = SupersedeRequest(
391
+ body=text,
392
+ expected_version=expected_version,
393
+ anchor=Anchor.from_dict(dict(anchor)) if anchor is not None else UNSET,
394
+ origin=Origin(kind=OriginKind(origin_kind)) if origin_kind is not None else UNSET,
395
+ workspace=_opt(workspace),
396
+ retirement=_opt(retirement),
397
+ kind=SupersedeRequestKind(kind) if kind is not None else UNSET,
398
+ derives_from=list(derives_from) if derives_from is not None else UNSET,
399
+ reason=_opt(reason),
400
+ format_=_opt(format),
401
+ title=_opt(title),
402
+ skill=skill_fields,
403
+ document=document_fields,
404
+ )
405
+ return self._write(
406
+ idempotency_key,
407
+ lambda key: supersede_memory.sync_detailed(
408
+ replaces, client=self._api, body=successor, idempotency_key=key
409
+ ),
410
+ )
411
+
412
+ def read(
413
+ self,
414
+ artifact_id: str | None = None,
415
+ *,
416
+ query: str | None = None,
417
+ workspace: str | None = None,
418
+ k: int | None = None,
419
+ kinds: Sequence[str] | None = None,
420
+ include_text: bool | None = None,
421
+ include_unreviewed: bool | None = None,
422
+ max_tokens: int | None = None,
423
+ search: str | None = None,
424
+ match: str | None = None,
425
+ own: bool | None = None,
426
+ claim_key: str | None = None,
427
+ state: str | None = None,
428
+ prefix: str | None = None,
429
+ since: datetime.datetime | None = None,
430
+ until: datetime.datetime | None = None,
431
+ limit: int | None = None,
432
+ cursor: str | None = None,
433
+ anchor_repo: str | None = None,
434
+ anchor_path_prefix: str | None = None,
435
+ origin_kinds: Sequence[str] | None = None,
436
+ sources: str | Sequence[str] | None = None,
437
+ as_of: datetime.datetime | None = None,
438
+ ) -> Memory | RecallResponse | MemoryPage:
439
+ """Read in `oml_read`'s three modes (ADR-0039 d4). `artifact_id`
440
+ fetches one version with its text, a `Memory`. `query` recalls over
441
+ promoted rows in `workspace`, else the key's default workspace, and the
442
+ caller's own held rows with `include_unreviewed`, a `RecallResponse`.
443
+ Neither reads one page of the catalog, newest first: what the key
444
+ reads in `workspace`'s subtree, every kind unless `kinds`, entries
445
+ without text unless `include_text`, per-kind counts on the first page;
446
+ or with `own=True` the key's own rows with their text, a `MemoryPage`
447
+ (ADR-0092 d6).
448
+ A recall's `sources` is `"scope"`, `"wide"` or a list of workspace names
449
+ searched alone, where the tenant enabled federation (ADR-0072 d5).
450
+ `as_of`, in every mode, reads memory as it was at that past instant
451
+ under today's access; the listing then defaults to `own=False`
452
+ (ADR-0059 d14, d19).
453
+ An argument outside the mode, and `query` beside `artifact_id`, raise
454
+ `request.validation` naming it before anything is sent; only the
455
+ fields given are sent."""
456
+ recall = {
457
+ "workspace": workspace,
458
+ "k": k,
459
+ "kinds": kinds,
460
+ "include_text": include_text,
461
+ "include_unreviewed": include_unreviewed,
462
+ "max_tokens": max_tokens,
463
+ "search": search,
464
+ "match": match,
465
+ "sources": sources,
466
+ }
467
+ listing = {
468
+ "own": own,
469
+ "claim_key": claim_key,
470
+ "state": state,
471
+ "prefix": prefix,
472
+ "since": since,
473
+ "until": until,
474
+ "limit": limit,
475
+ "cursor": cursor,
476
+ }
477
+ origin = {
478
+ "anchor_repo": anchor_repo,
479
+ "anchor_path_prefix": anchor_path_prefix,
480
+ "origin_kinds": origin_kinds,
481
+ }
482
+ if artifact_id is not None:
483
+ if query is not None:
484
+ raise _invalid(
485
+ "query",
486
+ "query is refused with artifact_id: artifact_id fetches one version and "
487
+ "query recalls, so pass one",
488
+ )
489
+ _outside_mode(recall | listing | origin, (), "get")
490
+ return self._send(
491
+ lambda: get_memory.sync_detailed(artifact_id, client=self._api, as_of=_opt(as_of))
492
+ ).parsed
493
+ if query is not None:
494
+ _outside_mode(listing, READ_RECALL, "recall")
495
+ request = RecallRequest(
496
+ query=query,
497
+ workspace=_opt(workspace),
498
+ k=_opt(k),
499
+ kinds=[ClaimKind(kind) for kind in kinds] if kinds is not None else UNSET,
500
+ include_text=_opt(include_text),
501
+ include_unreviewed=_opt(include_unreviewed),
502
+ max_tokens=_opt(max_tokens),
503
+ search=RecallRequestSearch(search) if search is not None else UNSET,
504
+ match=RecallRequestMatch(match) if match is not None else UNSET,
505
+ anchor_repo=_opt(anchor_repo),
506
+ anchor_path_prefix=_opt(anchor_path_prefix),
507
+ origin_kinds=[OriginKind(k) for k in origin_kinds]
508
+ if origin_kinds is not None
509
+ else UNSET,
510
+ sources=UNSET
511
+ if sources is None
512
+ else RecallRequestSourcesType0(sources)
513
+ if isinstance(sources, str)
514
+ else list(sources),
515
+ as_of=_opt(as_of),
516
+ )
517
+ return self._send(
518
+ lambda: recall_memories.sync_detailed(client=self._api, body=request)
519
+ ).parsed
520
+ _outside_mode(recall, READ_LISTING, "listing")
521
+ return self._listing(
522
+ workspace=workspace,
523
+ as_of=as_of,
524
+ kinds=kinds,
525
+ include_text=include_text,
526
+ **listing,
527
+ **origin,
528
+ )
529
+
530
+ def _listing(
531
+ self,
532
+ *,
533
+ own: bool | None = None,
534
+ workspace: str | None = None,
535
+ claim_key: str | None = None,
536
+ state: str | None = None,
537
+ kinds: Sequence[str] | None = None,
538
+ prefix: str | None = None,
539
+ include_text: bool | None = None,
540
+ since: datetime.datetime | None = None,
541
+ until: datetime.datetime | None = None,
542
+ limit: int | None = None,
543
+ cursor: str | None = None,
544
+ anchor_repo: str | None = None,
545
+ anchor_path_prefix: str | None = None,
546
+ origin_kinds: Sequence[str] | None = None,
547
+ as_of: datetime.datetime | None = None,
548
+ ) -> MemoryPage:
549
+ """One page of `GET /v1/memories`: the catalog, unless `own` is true
550
+ (ADR-0092 d6); the own-work list carries its text."""
551
+ return self._send(
552
+ lambda: list_memories.sync_detailed(
553
+ client=self._api,
554
+ own=bool(own),
555
+ as_of=_opt(as_of),
556
+ claim_key=_opt(claim_key),
557
+ state=_opt(state),
558
+ kinds=[ClaimKind(k) for k in kinds] if kinds is not None else UNSET,
559
+ prefix=_opt(prefix),
560
+ include_text=True if own else _opt(include_text),
561
+ workspace=_opt(workspace),
562
+ since=_opt(since),
563
+ until=_opt(until),
564
+ limit=_opt(limit),
565
+ cursor=_opt(cursor),
566
+ anchor_repo=_opt(anchor_repo),
567
+ anchor_path_prefix=_opt(anchor_path_prefix),
568
+ origin_kinds=[OriginKind(k) for k in origin_kinds]
569
+ if origin_kinds is not None
570
+ else UNSET,
571
+ )
572
+ ).parsed
573
+
574
+ def withdraw(
575
+ self,
576
+ artifact_id: str,
577
+ *,
578
+ reason: str | None = None,
579
+ idempotency_key: str | None = None,
580
+ ) -> Written[WithdrawResult]:
581
+ """Withdraw a held version this key wrote, for a mistaken write: it is
582
+ kept as withdrawn, leaves every review queue and is never served; no
583
+ reviewer is involved (ADR-0083 d13). Only a held version is withdrawn
584
+ (`memory.not_held`), and only by its author (`access.author_only`)."""
585
+ request = WithdrawRequest(reason=_opt(reason))
586
+ return self._write(
587
+ idempotency_key,
588
+ lambda key: withdraw_memory.sync_detailed(
589
+ artifact_id, client=self._api, body=request, idempotency_key=key
590
+ ),
591
+ )
592
+
593
+ def pages(self, **filters: Any) -> Iterator[MemoryPage]:
594
+ """Every page of `read`'s listing, following `next_cursor` until it is
595
+ null, with the same filters on every page. Cursors are positions, not
596
+ snapshots: a row that changes between pages can be missed or repeated."""
597
+ if "cursor" in filters:
598
+ raise TypeError("pages() follows the cursor itself; pass filters only")
599
+ cursor = None
600
+ while True:
601
+ page = self._listing(**filters, cursor=cursor)
602
+ yield page
603
+ if not page.next_cursor:
604
+ return
605
+ cursor = page.next_cursor
606
+
607
+ def iter_memories(self, **filters: Any) -> Iterator[MemorySummary]:
608
+ """Every row of `read`'s listing, across pages; see `pages`."""
609
+ for page in self.pages(**filters):
610
+ yield from page.items
611
+
612
+ def skills(
613
+ self,
614
+ workspace: str | None = None,
615
+ *,
616
+ include_own_held: bool | None = None,
617
+ cursor: str | None = None,
618
+ ) -> SkillSet:
619
+ """One page of the skills offered at `workspace`, else the key's
620
+ default workspace: names, descriptions and resource URIs, 50 a page,
621
+ without bodies (ADR-0080 d11). `include_own_held` offers the key's own
622
+ held skills too, each marked unreviewed. A body is `read` with the
623
+ skill's `artifact_id`. `set_digest` is the same on every page of one
624
+ set, so a caller compares it to tell the set changed."""
625
+ return self._send(
626
+ lambda: get_skills.sync_detailed(
627
+ client=self._api,
628
+ workspace=_opt(workspace),
629
+ include_own_held=_opt(include_own_held),
630
+ cursor=_opt(cursor),
631
+ )
632
+ ).parsed
633
+
634
+ def iter_skills(
635
+ self, workspace: str | None = None, *, include_own_held: bool | None = None
636
+ ) -> Iterator[ServedSkill]:
637
+ """Every skill of the offered set, across pages, following
638
+ `next_cursor` until it is null; see `skills`."""
639
+ cursor = None
640
+ while True:
641
+ page = self.skills(workspace, include_own_held=include_own_held, cursor=cursor)
642
+ yield from page.skills
643
+ if not page.next_cursor:
644
+ return
645
+ cursor = page.next_cursor
646
+
647
+ # -- workspaces and the journal (/v2) -------------------------------------
648
+
649
+ def workspace(self, workspace: str | None = None) -> WorkspaceView:
650
+ """One workspace node, by id or name, with this key's view of it: its
651
+ children, edges, effective verbs and permission epoch. Omitted, the
652
+ key's default workspace, which `GET /v2/whoami` names; a key with none
653
+ raises `request.workspace_unresolved`."""
654
+ if workspace is None:
655
+ me = self._send(lambda: whoami.sync_detailed(client=self._api)).parsed
656
+ if me.default_workspace is None:
657
+ raise refused_locally(
658
+ 422,
659
+ "request.workspace_unresolved",
660
+ "no workspace was named and this key has no default_workspace",
661
+ UNRESOLVED_RULE,
662
+ None,
663
+ )
664
+ workspace = me.default_workspace.id
665
+ node = workspace
666
+ return self._send(lambda: get_workspace.sync_detailed(node, client=self._api)).parsed
667
+
668
+ def events(
669
+ self,
670
+ *,
671
+ after_seq: int | None = None,
672
+ workspace: str | None = None,
673
+ limit: int | None = None,
674
+ ) -> EventsPage:
675
+ """One page of the journal tail of `workspace`'s subtree, else the key's
676
+ default workspace's, in seq order after `after_seq`; pass the page's
677
+ `next_after_seq` back to resume. Digests only, never claim text."""
678
+ return self._send(
679
+ lambda: tail_events.sync_detailed(
680
+ client=self._api,
681
+ after_seq=_opt(after_seq),
682
+ workspace=_opt(workspace),
683
+ limit=_opt(limit),
684
+ )
685
+ ).parsed
686
+
687
+ # -- the review ceremony (/v2), for a reviewer key ------------------------
688
+
689
+ def review_next(self) -> Serve | None:
690
+ """Serve exactly one held item to this reviewer, or None when nothing waits."""
691
+ key = str(uuid.uuid4())
692
+ response = self._send(
693
+ lambda: review_next.sync_detailed(client=self._api, idempotency_key=key)
694
+ )
695
+ return response.parsed if response.status_code == 200 else None
696
+
697
+ def approve(
698
+ self,
699
+ serve_id: str | None = None,
700
+ *,
701
+ reason: str | None = None,
702
+ idempotency_key: str | None = None,
703
+ ) -> Written[VerdictResult]:
704
+ """Approve the `serve_id` that `review_next` returned, or, omitted, the
705
+ one item this key has claimed (ADR-0039 d10); the id is opaque and
706
+ never built here."""
707
+ return self._verdict(VerdictRequestVerdict.APPROVE, serve_id, reason, idempotency_key)
708
+
709
+ def reject(
710
+ self,
711
+ serve_id: str | None = None,
712
+ *,
713
+ reason: str,
714
+ idempotency_key: str | None = None,
715
+ ) -> Written[VerdictResult]:
716
+ """Reject the `serve_id` that `review_next` returned, or, omitted, the
717
+ one item this key has claimed, with the reason a rejection requires."""
718
+ return self._verdict(VerdictRequestVerdict.REJECT, serve_id, reason, idempotency_key)
719
+
720
+ def _verdict(
721
+ self,
722
+ verdict: VerdictRequestVerdict,
723
+ serve_id: str | None,
724
+ reason: str | None,
725
+ idempotency_key: str | None,
726
+ ) -> Written[VerdictResult]:
727
+ request = VerdictRequest(verdict=verdict, serve_id=_opt(serve_id), reason=_opt(reason))
728
+ return self._write(
729
+ idempotency_key,
730
+ lambda key: post_verdict.sync_detailed(
731
+ client=self._api, body=request, idempotency_key=key
732
+ ),
733
+ )