Request Management
Methods for retrieving and deleting requests and sessions.
mark_session_outcomemethodRecord an optional external success, failure, or unknown outcome for a session. Use unknown when the domain cannot determine a terminal result; it is an explicit outcome rather than an omitted outcome. Publish at least one request first. Emend derives user_id and source from the earliest request ordered by (created_at, request_id); neither is accepted from the caller.
source is a non-sensitive producer/workflow label, not a person or free-form description. A non-empty value must match ^[a-z0-9][a-z0-9._:-]{0,127}$ and must not contain user identifiers or PII.
success=True, recorded=False, and the same outcome_id, outcome_revision, outcome_contract_digest, and finalized_trajectory_digest. Any changed outcome, timestamp, label, value, metadata, contract, or finalized trajectory is rejected with success=False and reason="conflicting_finalization"; the original record is unchanged.The trajectory digest always covers the complete canonical trajectory. Outcome finalization does not truncate or reject a trajectory under the offline tuner's separate 64,000 byte and 8,000 cl100k_base token evidence limits.
During a rolling upgrade, a legacy row may have all four identity fields set to null. An exact retry still compares the caller payload and any available server-derived session context, but it cannot compare the absent contract or trajectory digests. An accepted retry preserves all four identity fields as null. A changed payload or available session context conflicts; the retry does not fabricate or backfill immutable identity.
response = client.mark_session_outcome( session_id="support_ticket_789", outcome="success", occurred_at=1785196800, label="issue_resolved", value=5.0, metadata={"survey": "post-chat"},)Sessions may remain unmarked. Outcomes are stored as caller-authored domain facts; they do not update profiles or playbooks. The identity digests are opaque integrity values and are not configuration inputs.
get_session_outcomesmethodRead outcomes with optional exact filters. value and metadata are returned but are intentionally not filterable. The optional source filter uses the same non-sensitive producer/workflow label contract.
response = client.get_session_outcomes( user_id="user_123", source="support-agent", outcome="success", label="issue_resolved", start_time=1785110400, end_time=1785196800, top_k=100,)See Request Models for request, response, bounds, and pagination fields.
get_requestsmethodGet requests with their associated interactions, grouped by session.
response = client.get_requests( user_id="user_123", top_k=50)| Prop | Type |
|---|---|
user_id | string |
request_id | string |
session_id | string |
source | string |
start_time | datetime |
end_time | datetime |
top_k | integer |
Returns GetRequestsResponse, containing Session, RequestData, and Request objects — see Request Models.
delete_requestmethodDelete a request and all its associated interactions.
response = client.delete_request( request_id, wait_for_response=False)| Prop | Type |
|---|---|
request_idrequired | string |
wait_for_response | boolean |
Returns DeleteRequestResponse — see Request Models.
delete_sessionmethodDelete all requests and interactions in a session.
response = client.delete_session( session_id, wait_for_response=False)| Prop | Type |
|---|---|
session_idrequired | string |
wait_for_response | boolean |
Returns DeleteSessionResponse — see Request Models.
Bulk Delete Operations
delete_requests_by_idsmethodDelete multiple requests by their IDs.
response = client.delete_requests_by_ids(request_ids=["req_1", "req_2"])| Prop | Type |
|---|---|
request_idsrequired | list[string] |
Returns: BulkDeleteResponse with success, deleted_count, and message.
delete_all_interactionsmethodDelete all requests and their associated interactions.
response = client.delete_all_interactions()Returns: BulkDeleteResponse with success, deleted_count, and message.