1import { defineCommand } from '@lssm-tech/lib.contracts-spec';
2import { defineSchemaModel, ScalarTypeEnum } from '@lssm-tech/lib.schema';
3import {
4	AssistantAnswerIRModel,
5	LLMCallEnvelopeModel,
6} from '../entities/models';
7
8export const AssistantAnswerContract = defineCommand({
9	meta: {
10		key: 'assistant.answer',
11		version: '1.0.0',
12		stability: 'experimental',
13		owners: ['@examples'],
14		tags: ['assistant', 'policy', 'locale', 'jurisdiction', 'knowledge'],
15		description:
16			'Answer a user question using a KB snapshot with strict locale/jurisdiction gating.',
17		goal: 'Provide policy-safe answers that cite a KB snapshot or refuse.',
18		context:
19			'Called by UI or workflows; must fail-closed if envelope is invalid or citations are missing.',
20	},
21	io: {
22		input: AssistantQuestionInput,
23		output: AssistantAnswerIRModel,
24		errors: {
25			LOCALE_REQUIRED: {
26				description: 'Locale is required and must be supported',
27				http: 400,
28				gqlCode: 'LOCALE_REQUIRED',
29				when: 'locale is missing or unsupported',
30			},
31			JURISDICTION_REQUIRED: {
32				description: 'Jurisdiction is required',
33				http: 400,
34				gqlCode: 'JURISDICTION_REQUIRED',
35				when: 'jurisdiction is missing',
36			},
37			KB_SNAPSHOT_REQUIRED: {
38				description: 'KB snapshot id is required',
39				http: 400,
40				gqlCode: 'KB_SNAPSHOT_REQUIRED',
41				when: 'kbSnapshotId is missing',
42			},
43			CITATIONS_REQUIRED: {
44				description: 'Answers must include citations to a KB snapshot',
45				http: 422,
46				gqlCode: 'CITATIONS_REQUIRED',
47				when: 'answer has no citations',
48			},
49			SCOPE_VIOLATION: {
50				description:
51					'Answer violates allowed scope and must be refused/escalated',
52				http: 403,
53				gqlCode: 'SCOPE_VIOLATION',
54				when: 'output includes forbidden content under the given allowedScope',
55			},
56		},
57	},
58	policy: { auth: 'user' },
59});