Schemas

Playbook Models

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

UserPlaybookmodel

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
`user_playbook_id`	integer
`user_id`	string
`agent_version`required	string
`request_id`required	string
`playbook_name`	string
`created_at`	integer
`content`	string
`trigger`	string
`rationale`	string
`source`	string
`status`	Status
`source_interaction_ids`	array[integer]
`source_span`	string \| null
`tags`	array[string] \| null

AgentPlaybookmodel

Represents an agent playbook consolidated from multiple user playbooks.

Prop	Type
`agent_playbook_id`	integer
`playbook_name`	string
`agent_version`required	string
`created_at`	integer
`content`required	string
`trigger`	string
`rationale`	string
`playbook_status`required	PlaybookStatus
`playbook_metadata`required	string
`status`	Status
`tags`	array[string] \| null

GetUserPlaybooksRequestrequest model

Request model for getting user playbooks.

Prop	Type
`limit`	integer
`user_playbook_id`	integer
`user_id`	string
`request_id`	string
`query`	string
`playbook_name`	string
`agent_version`	string
`start_time`	datetime
`end_time`	datetime
`status_filter`	array[Status]
`tags`	array[string]

GetUserPlaybooksResponseresponse model

Response model for getting user playbooks.

Prop	Type
`success`required	boolean
`user_playbooks`required	array[UserPlaybook]
`msg`	string

AddUserPlaybookRequestrequest model

Request model for adding user playbooks directly to storage.

Prop	Type
`user_playbooks`required	array[UserPlaybook]

AddUserPlaybookResponseresponse model

Response model for adding user playbooks.

Prop	Type
`success`required	boolean
`message`	string
`added_count`	integer

AddAgentPlaybookRequestrequest model

Request model for adding agent playbooks directly to storage.

Prop	Type
`agent_playbooks`required	array[AgentPlaybook]

AddAgentPlaybookResponseresponse model

Response model for adding agent playbooks.

Prop	Type
`success`required	boolean
`message`	string
`added_count`	integer

GetAgentPlaybooksRequestrequest model

Request model for getting agent playbooks.

Prop	Type
`limit`	integer
`agent_playbook_id`	integer
`query`	string
`playbook_name`	string
`agent_version`	string
`start_time`	datetime
`end_time`	datetime
`status_filter`	array[Status]
`playbook_status_filter`	PlaybookStatus
`tags`	array[string]

GetAgentPlaybooksResponseresponse model

Response model for getting agent playbooks.

Prop	Type
`success`required	boolean
`agent_playbooks`required	array[AgentPlaybook]
`msg`	string

RunPlaybookAggregationRequestrequest model

Request model for running playbook aggregation.

Prop	Type
`agent_version`required	string
`playbook_name`	string

RunPlaybookAggregationResponseresponse model

Response model for playbook aggregation requests.

Prop	Type
`success`required	boolean
`message`	string

DeleteAgentPlaybookRequestrequest model

Request model for deleting an agent playbook.

Prop	Type
`agent_playbook_id`required	integer

DeleteAgentPlaybookResponseresponse model

Response model for agent playbook deletion requests.

Prop	Type
`success`required	boolean
`message`	string

DeleteUserPlaybookRequestrequest model

Request model for deleting a user playbook.

Prop	Type
`user_playbook_id`required	integer

DeleteUserPlaybookResponseresponse model

Response model for user playbook deletion requests.

Prop	Type
`success`required	boolean
`message`	string

ReviewUserPlaybooksRequestrequest model

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

Prop	Type
`start_time`required	datetime
`end_time`required	datetime
`top_k`	integer
`report_only`	boolean

ReviewUserPlaybookEditmodel

Complete replacement fields proposed for an edit decision.

Prop	Type
`content`required	string
`trigger`required	string
`rationale`required	string

ReviewUserPlaybookResultmodel

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
`user_playbook_id`required	integer
`decision`required	"accept" \| "edit" \| "reject" \| "skip"
`reason_code`required	"grounded_useful" \| "unsupported_evidence" \| "generic" \| "speculative" \| "unsupported_causality" \| "unseen_artifact" \| "redundant" \| "late_trigger" \| "compound" \| "internal_status" \| "absence_inference" \| "not_agent_decision" \| "evidence_unavailable"
`reason`	string \| null
`edit`	ReviewUserPlaybookEdit \| null
`applied`	boolean
`successor_user_playbook_id`	integer \| null

ReviewUserPlaybooksResponseresponse model

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
`success`required	boolean
`report_only`required	boolean
`run_id`	string \| null
`selected_count`	integer
`accepted_count`	integer
`edited_count`	integer
`rejected_count`	integer
`skipped_count`	integer
`results`	array[ReviewUserPlaybookResult]
`msg`	string \| null

RerunPlaybookGenerationRequestrequest model

Request model for rerunning playbook generation.

Prop	Type
`agent_version`required	string
`start_time`	datetime
`end_time`	datetime
`playbook_name`	string
`source`	string

RerunPlaybookGenerationResponseresponse model

Response model for playbook generation rerun requests.

Prop	Type
`success`required	boolean
`msg`	string
`playbooks_generated`	integer
`operation_id`	string

ManualPlaybookGenerationRequestrequest model

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

Prop	Type
`agent_version`required	string
`source`	string
`playbook_name`	string

ManualPlaybookGenerationResponseresponse model

Response model for manual playbook generation.

Prop	Type
`success`required	boolean
`msg`	string
`playbooks_generated`	integer

PreviousInteraction Models Next Profile Models