Schemas

Playbook Models

Data structures for user playbooks and agent playbooks -- collecting, aggregating, and managing agent improvement data.

Durable aggregation receipts

SubmitPlaybookAggregationRequest requires request_id and agent_version, both nonblank strings of 1–200 characters.

PlaybookAggregationOperation is returned by durable aggregation submission and status lookup:

Field	Type	Default / meaning
`operation_id`	str	Server-generated tracking ID
`request_id`	str	Caller-supplied idempotency key
`agent_version`	str	Version being aggregated
`status`	str	queued, running, retrying, succeeded, or failed
`created_at`, `updated_at`	int	Unix seconds
`started_at`, `completed_at`	int or null	Unix seconds; null until reached
`attempts`	int	0 initially
`next_attempt_at`	int or null	Retry/admission time, Unix seconds
`error`	str or null	Safe failure code
`result`	PlaybookAggregationResult or null	Committed result on success

PlaybookAggregationResult contains clusters_found, user_playbooks_processed, and playbooks_generated (integers defaulting to 0), and skipped (an optional reason, default null).

UserPlaybook

Represents a user playbook row containing agent guidance. Rows are usually extracted from user interactions, but supported manual and playbook-optimizer workflows can also create rows.

Prop	Type	Default	Description
`user_playbook_id?`	`integer`	`0`	Unique identifier for the user playbook
`user_id?`	`string`	`—`	Identifier of the user (optional for backward compatibility)
`agent_version`	`string`	`—`	Version of the agent
`request_id`	`string`	`—`	Request ID that generated this playbook entry
`playbook_name?`	`string`	`""`	Name of the playbook type
`created_at?`	`integer`	`Current time`	Unix timestamp when the playbook entry was created
`content?`	`string`	`""`	The main actionable content of the playbook entry
`trigger?`	`string`	`—`	The condition/context when this playbook rule applies
`rationale?`	`string`	`—`	Explanation of why this playbook entry was extracted
`source?`	`string`	`—`	Provenance of the playbook row, usually the originating interaction source or supported write workflow.
`status?`	Status	`—`	Processing status (None=current, PENDING=from rerun, ARCHIVED=old)
`source_interaction_ids?`	`array[integer]`	`[]`	IDs of source interactions that generated this playbook entry
`source_span?`	`string \| null`	`—`	Verbatim source text span the playbook entry was extracted from, when available
`tags?`	`array[string] \| null`	`—`	Tags assigned to this playbook. Null means not yet tagged; an empty array means tagging ran and no tag matched.

AgentPlaybook

Represents an agent playbook consolidated from multiple user playbooks.

Prop	Type	Default	Description
`agent_playbook_id?`	`integer`	`0`	Unique identifier for the agent playbook
`playbook_name?`	`string`	`""`	Name of the playbook type
`agent_version`	`string`	`—`	Version of the agent
`created_at?`	`integer`	`Current time`	Unix timestamp when the agent playbook was created
`content`	`string`	`—`	The main actionable content of the playbook
`trigger?`	`string`	`—`	The condition/context when this playbook rule applies
`rationale?`	`string`	`—`	Explanation of why this playbook entry was extracted
`playbook_status`	PlaybookStatus	`—`	Approval status (PENDING, APPROVED, REJECTED)
`playbook_metadata`	`string`	`—`	Additional metadata about the playbook
`status?`	Status	`—`	Processing status for aggregation tracking
`tags?`	`array[string] \| null`	`—`	Tags assigned to this playbook. Null means not yet tagged; an empty array means tagging ran and no tag matched.

GetUserPlaybooksRequest

Request model for getting user playbooks.

Prop	Type	Default	Description
`limit?`	`integer`	`100`	Maximum number of results to return
`user_playbook_id?`	`integer`	`—`	Exact user playbook ID filter
`user_id?`	`string`	`—`	Filter by user ID
`request_id?`	`string`	`—`	Filter by generating request ID
`query?`	`string`	`—`	Case-insensitive text filter across visible user playbook fields
`playbook_name?`	`string`	`—`	Filter by playbook name
`agent_version?`	`string`	`—`	Filter by agent version
`start_time?`	`datetime`	`—`	Filter by created-at start time
`end_time?`	`datetime`	`—`	Filter by created-at end time
`status_filter?`	array[Status]	`—`	Filter by status
`tags?`	`array[string]`	`—`	Optional tag filter. Matches user playbooks that have any requested tag.

GetUserPlaybooksResponse

Response model for getting user playbooks.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the request was successful
`user_playbooks`	array[UserPlaybook]	`—`	List of user playbooks
`msg?`	`string`	`—`	Additional message

AddUserPlaybookRequest

Request model for adding user playbooks directly to storage.

Prop	Type	Default	Description
`user_playbooks`	array[UserPlaybook]	`—`	List of user playbooks to add

AddUserPlaybookResponse

Response model for adding user playbooks.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the operation was successful
`message?`	`string`	`""`	Additional information about the operation
`added_count?`	`integer`	`0`	Number of playbook entries added

AddAgentPlaybookRequest

Request model for adding agent playbooks directly to storage.

Prop	Type	Default	Description
`agent_playbooks`	array[AgentPlaybook]	`—`	List of agent playbooks to add

AddAgentPlaybookResponse

Response model for adding agent playbooks.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the operation was successful
`message?`	`string`	`—`	Additional information about the operation
`added_count?`	`integer`	`0`	Number of agent playbooks added

GetAgentPlaybooksRequest

Request model for getting agent playbooks.

Prop	Type	Default	Description
`limit?`	`integer`	`100`	Maximum number of results to return
`agent_playbook_id?`	`integer`	`—`	Exact agent playbook ID filter
`query?`	`string`	`—`	Case-insensitive text filter across visible agent playbook fields
`playbook_name?`	`string`	`—`	Filter by playbook name
`agent_version?`	`string`	`—`	Filter by agent version
`start_time?`	`datetime`	`—`	Filter by created-at start time
`end_time?`	`datetime`	`—`	Filter by created-at end time
`status_filter?`	array[Status]	`—`	Filter by status
`playbook_status_filter?`	PlaybookStatus	`APPROVED`	Filter by playbook status
`tags?`	`array[string]`	`—`	Optional tag filter. Matches agent playbooks that have any requested tag.

GetAgentPlaybooksResponse

Response model for getting agent playbooks.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the request was successful
`agent_playbooks`	array[AgentPlaybook]	`—`	List of agent playbooks
`msg?`	`string`	`—`	Additional message

RunPlaybookAggregationRequest

Request model for running playbook aggregation.

Prop	Type	Default	Description
`agent_version`	`string`	`—`	Agent version to aggregate playbooks for
`playbook_name?`	`string`	`—`	Deprecated compatibility field. Accepted but ignored; aggregation uses the singleton playbook stream.

RunPlaybookAggregationResponse

Response model for playbook aggregation requests.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the aggregation was successful
`message?`	`string`	`""`	Additional information about the operation

DeleteAgentPlaybookRequest

Request model for deleting an agent playbook.

Prop	Type	Default	Description
`agent_playbook_id`	`integer`	`—`	Identifier of the agent playbook to delete

DeleteAgentPlaybookResponse

Response model for agent playbook deletion requests.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the deletion was successful
`message?`	`string`	`""`	Additional information about the operation

DeleteUserPlaybookRequest

Request model for deleting a user playbook.

Prop	Type	Default	Description
`user_playbook_id`	`integer`	`—`	Identifier of the user playbook to delete

DeleteUserPlaybookResponse

Response model for user playbook deletion requests.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the deletion was successful
`message?`	`string`	`""`	Additional information about the operation

ReviewUserPlaybooksRequest

Selects current user playbooks by inclusive creation-time bounds and reviews the newest matches first.

Prop	Type	Default	Description
`start_time`	`datetime`	`—`	Inclusive lower created-at bound
`end_time`	`datetime`	`—`	Inclusive upper created-at bound; must be after start_time
`top_k?`	`integer`	`10`	Maximum number of matching current playbooks to review (1-100)
`report_only?`	`boolean`	`true`	Only report decisions when true; accept the run and apply each decision newest-first in the background when false

ReviewUserPlaybookEdit

Complete replacement fields proposed for an edit decision.

Prop	Type	Default	Description
`content`	`string`	`—`	Revised actionable playbook content
`trigger`	`string`	`—`	Revised condition under which the playbook applies
`rationale`	`string`	`—`	Revised evidence-grounded rationale

One selected playbook's review decision. skip means the playbook could not be reviewed because its finalized generation-window provenance or validated evidence is absent, a required interaction/request is missing, or provenance ownership does not match — not that the reviewer chose to leave it unchanged, which is accept. Historical context uses the full run-level interaction window, not only the playbook's cited-evidence subset, and is independent of the current extractor window and source filter. A skipped playbook is never written to.

Prop	Type	Default	Description
`user_playbook_id`	`integer`	`—`	Reviewed incumbent playbook ID
`decision`	`"accept" \| "edit" \| "reject" \| "skip"`	`—`	Public review decision
`reason_code`	`"grounded_useful" \| "unsupported_evidence" \| "generic" \| "speculative" \| "unsupported_causality" \| "unseen_artifact" \| "redundant" \| "late_trigger" \| "compound" \| "internal_status" \| "absence_inference" \| "not_agent_decision" \| "evidence_unavailable"`	`—`	Machine-readable reviewer reason. All values except evidence_unavailable come from the reviewer; evidence_unavailable accompanies decision=skip and means the row could not be reviewed at all.
`reason?`	`string \| null`	`—`	Optional reviewer explanation
`edit?`	ReviewUserPlaybookEdit \| null	`—`	Replacement fields for an edit decision
`applied?`	`boolean`	`false`	Whether this decision completed successfully in apply mode
`successor_user_playbook_id?`	`integer \| null`	`—`	Current replacement ID created for an applied edit

ReviewUserPlaybooksResponse

Review report, or an acknowledgement for a background apply run. In report mode results holds one entry per selected playbook. In apply mode the run is dispatched in the background, so the response carries only run_id and an empty results; a later failure stops the run but leaves earlier decisions committed, and each applied edit is recorded on its replacement's lineage under run_id.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the report completed, or the apply run was accepted
`report_only`	`boolean`	`—`	Mode used for this run
`run_id?`	`string \| null`	`—`	Unique review-run identifier; correlates the run's lineage events
`selected_count?`	`integer`	`0`	Number of matching playbooks selected for the run (report mode)
`accepted_count?`	`integer`	`0`	Number of accept decisions
`edited_count?`	`integer`	`0`	Number of edit decisions
`rejected_count?`	`integer`	`0`	Number of reject decisions
`skipped_count?`	`integer`	`0`	Number of playbooks skipped as unreviewable
`results?`	array[ReviewUserPlaybookResult]	`[]`	Per-playbook decisions in selection order; empty in apply mode
`msg?`	`string \| null`	`—`	Run summary or failure message

RerunPlaybookGenerationRequest

Request model for rerunning playbook generation.

Prop	Type	Default	Description
`agent_version`	`string`	`—`	Agent version to evaluate
`start_time?`	`datetime`	`—`	Filter interactions from this time
`end_time?`	`datetime`	`—`	Filter interactions until this time
`playbook_name?`	`string`	`—`	Deprecated compatibility field. Accepted but ignored; rerun uses the singleton playbook extractor.
`source?`	`string`	`—`	Filter interactions by source

RerunPlaybookGenerationResponse

Response model for playbook generation rerun requests.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the operation was successful
`msg?`	`string`	`—`	Additional information
`playbooks_generated?`	`integer`	`—`	Number of playbook entries generated
`operation_id?`	`string`	`"rerun_playbook_generation"`	Operation identifier for tracking

ManualPlaybookGenerationRequest

Request model for manually triggering playbook generation with window-sized interactions. Creates playbook entries with CURRENT status directly (no upgrade needed).

Prop	Type	Default	Description
`agent_version`	`string`	`—`	Agent version to evaluate
`source?`	`string`	`—`	Filter interactions by source
`playbook_name?`	`string`	`—`	Deprecated compatibility field. Accepted but ignored; manual generation uses the singleton playbook extractor when manual triggering is allowed.

ManualPlaybookGenerationResponse

Response model for manual playbook generation.

Prop	Type	Default	Description
`success`	`boolean`	`—`	Whether the operation was successful
`msg?`	`string`	`—`	Additional information
`playbooks_generated?`	`integer`	`—`	Number of playbook entries generated

Client Methods

Interaction Models

Configuration Guide

Searching Learned Context