Dispositions

Overview

A disposition is a structured determination of what was learned from a session. While key results capture individual query outputs, a disposition captures the session's overall conclusion in a machine-readable format.

Dispositions are useful when sessions are part of a repeatable workflow — for example, investigating a series of cost anomalies where each session should conclude with a risk level, estimated savings, and notes. The disposition schema ensures that every session in the workflow produces a consistent, comparable output.

A disposition has two parts:

• Disposition Schema — Defined by the user when creating or editing a session. Specifies the legal fields and their types. Think of this as a form template.
• Disposition — The actual values, set by the AI during the session when the user agrees. Think of this as the filled-in form.

Disposition Schema

The disposition schema is a JSON object where each key is a field name and each value describes the field's type. For example:

{
  "risk_level": "NONE|LOW|MEDIUM|HIGH",
  "estimated_savings": "Number",
  "notes": "String"
}

This schema defines three fields:

The schema is injected into the AI's prompt context so it knows what fields are available and what values are legal.

Defining a Schema

You can define a disposition schema in two places:

1. When creating a new session — The new session form includes a "Disposition Schema" editor below the starting request. This is the recommended approach, since the schema is included in the AI's initial prompt.

2. When editing an existing session — From the project detail page, click the pencil icon on a session to open the edit panel, which includes the disposition schema editor. Note that editing the schema on an existing session updates it for future interactions but does not retroactively change the AI's initial prompt.

Schema Field Types

All fields are optional — the AI can set a partial disposition containing only some of the schema's fields. This allows incremental determination where the AI sets known fields first and fills in others as the investigation progresses.

How the AI Sets a Disposition

The AI sets a disposition using the SET_DISPOSITION tool. This tool is only available when the session has a disposition schema defined. The flow is:

1. The AI investigates the user's request through database queries and metadata lookups.
2. When the AI has reached a conclusion, it proposes a disposition to the user using PROMPT_USER (e.g., "Based on my analysis, I'd recommend a disposition of risk_level: HIGH with estimated_savings: 50000. Shall I set this?").
3. The user agrees (or asks for adjustments).
4. The AI calls SET_DISPOSITION with a JSON object: SET_DISPOSITION {"risk_level": "HIGH", "estimated_savings": 50000}
5. The system validates the disposition against the schema and either accepts it or returns an error to the AI.
6. On success, the disposition appears in the session workspace and on the project's session list.

The AI is instructed to never call SET_DISPOSITION unless the user has explicitly agreed to the proposed disposition.

Validation Rules

When the AI calls SET_DISPOSITION, the system validates the provided values:

• The session must have a disposition schema defined.
• The disposition must be a valid JSON object.
• All keys in the disposition must exist in the schema (unknown keys are rejected).
• Each value must match its schema type:
  • Number fields must have a numeric value.
  • String fields must have a string value.
  • Enumerated list fields must have a value that exactly matches one of the pipe-separated options.
• Missing keys are allowed (partial dispositions are valid).

If validation fails, the AI receives an error message describing the problem and can retry.

Viewing Dispositions

Once a disposition is set, it appears in three places:

1. Session workspace — A green card at the top of the Key Results pane (both the compact sidebar view and the expanded view) showing each field and its value, marked with a flag icon.

2. Project detail page — Small green tags below the session name in the session list, showing each key-value pair. This gives a quick overview of session outcomes without opening each session.

3. Session detail API — The disposition is included in the session data returned by the detail endpoint, making it available for programmatic access.

Dispositions update in real-time — when the AI sets a disposition during an active session, it appears immediately without requiring a page refresh.

Editing a Schema After Creation

You can modify a session's disposition schema after creation using the session edit panel (pencil icon on the project detail page). Changes to the schema:

• Take effect for future AI interactions in the session.
• Do not retroactively change the initial prompt that was sent when the session started.
• Do not invalidate an existing disposition (the existing disposition is retained even if it no longer matches the updated schema).

For best results, define the disposition schema before starting the session so the AI has the full context from the beginning.

Example Workflow

Scenario: A team is reviewing a set of pharmacy cost anomalies. Each anomaly gets its own session, and every session should conclude with a risk assessment.

1. Create a project called "Pharmacy Cost Anomaly Review" with a system prompt instructing the AI to investigate pharmacy cost patterns.

2. Start a new session for the first anomaly. In the disposition schema editor, define:

   • risk_level: Custom List — NONE|LOW|MEDIUM|HIGH
   • estimated_annual_impact: Number
   • recommended_action: String

3. The AI investigates the anomaly, querying the database and reviewing measure metadata.

4. The AI presents its findings: "This appears to be a high-risk anomaly with an estimated annual impact of $120,000. I'd recommend a formulary review. Shall I set the disposition?"

5. You reply: "Yes, set it."

6. The AI calls: SET_DISPOSITION {"risk_level": "HIGH", "estimated_annual_impact": 120000, "recommended_action": "Formulary review"}

7. The disposition appears in the session and on the project's session list, where you can see at a glance which anomalies are high-risk.

8. Repeat for each anomaly. The session list on the project detail page shows disposition tags for all reviewed anomalies, giving a dashboard-like overview.