Frame Detect Contract

Use POST /v1/ai/frame-detect to get a strict, versioned frame selection payload.

This contract is intended to remain provider-neutral. The decision runtime lives in Fastify, prompt composition stays server-only, and prompt-governance state belongs in Prisma-managed Postgres. In SaaS deployments, Neon is only the managed Postgres host.

Request Example

{
	"user_prompt": "Should we expand into enterprise accounts this quarter?",
	"candidate_frame_ids": "DF-001|DF-002|DF-003",
	"commit_state": "exploration",
	"org_doctrine": "Prefer reversible decisions when uncertainty is high.",
	"risk_context": "Team capacity is constrained and launch timing is critical."
}

Success Response Example

{
	"contract_version": "1.0.0",
	"primary_frame_id": "DF-001",
	"secondary_frame_ids": ["DF-002"],
	"confidence": 0.72,
	"missing_framing_questions": [
		{
			"intent": "clarify_objective",
			"question": "What objective metric defines success for this decision?"
		}
	],
	"warnings": ["Decision scope may be narrower than underlying problem."],
	"framing_risk": "medium",
	"premature_convergence_risk": "medium"
}

Error Examples

{
	"error": "Invalid payload"
}

{
	"error": "candidate_frame_ids must use pipe-delimited DF-### values"
}

{
	"error": "Invalid provider response"
}

Contract notes:

primary_frame_id and secondary_frame_ids must match DF-###.
confidence must be between 0 and 1.
framing_risk and premature_convergence_risk must be low, medium, or high.
Extra keys are rejected on both request and response contracts.
The contract is intentionally separate from any specific model vendor or orchestration product.

Quick Local Checks

Use these examples to quickly validate the endpoint during local integration work.

curl

curl -sS -X POST "http://localhost:4000/v1/ai/frame-detect" \
  -H "content-type: application/json" \
  -H "x-user-id: u1" \
  -H "x-org-id: o1" \
  -H "x-role: admin" \
  -d '{
    "user_prompt": "Should we expand into enterprise accounts this quarter?",
    "candidate_frame_ids": "DF-001|DF-002|DF-003",
    "commit_state": "exploration",
    "org_doctrine": "Prefer reversible decisions when uncertainty is high.",
    "risk_context": "Team capacity is constrained and launch timing is critical."
  }'

httpie

http POST "http://localhost:4000/v1/ai/frame-detect" \
  content-type:application/json \
  x-user-id:u1 \
  x-org-id:o1 \
  x-role:admin \
  user_prompt="Should we expand into enterprise accounts this quarter?" \
  candidate_frame_ids="DF-001|DF-002|DF-003" \
  commit_state="exploration" \
  org_doctrine="Prefer reversible decisions when uncertainty is high." \
  risk_context="Team capacity is constrained and launch timing is critical."