Skip to content

Commit e9efb0e

Browse files
author
Your Name
committed
feat: add generate v1.0.0 request + receipt schemas (A2A + Swarm + x402)
1 parent 502b222 commit e9efb0e

File tree

2 files changed

+389
-0
lines changed

2 files changed

+389
-0
lines changed

‎schemas/v1.0.0/commons/generate/receipts/generate.receipt.schema.json‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
{
2+
"$id": "https://commandlayer.org/schemas/v1.0.0/commons/generate/receipts/generate.receipt.schema.json",
3+
"$schema": "https://json-schema.org/draft/2020-12/schema",
4+
"title": "generate.receipt",
5+
"description": "Receipt for generate requests, extending the CommandLayer base receipt structure with generation-specific result and usage fields.",
6+
"type": "object",
7+
"allOf": [
8+
{
9+
"$ref": "https://commandlayer.org/schemas/v1.0.0/_shared/receipt.base.schema.json"
10+
},
11+
{
12+
"type": "object",
13+
"additionalProperties": false,
14+
"properties": {
15+
"x402": {
16+
"description": "x402 envelope describing the generate verb and version for this receipt.",
17+
"allOf": [
18+
{
19+
"$ref": "https://commandlayer.org/schemas/v1.0.0/_shared/x402.schema.json"
20+
},
21+
{
22+
"type": "object",
23+
"additionalProperties": false,
24+
"properties": {
25+
"verb": { "const": "generate" },
26+
"version": { "const": "1.0.0" }
27+
},
28+
"required": ["verb", "version"]
29+
}
30+
]
31+
},
32+
"result": {
33+
"description": "Generation result payload when status = 'success'.",
34+
"type": "object",
35+
"additionalProperties": false,
36+
"properties": {
37+
"content": {
38+
"description": "The primary generated content.",
39+
"type": "string",
40+
"minLength": 1,
41+
"maxLength": 500000
42+
},
43+
"format": {
44+
"description": "Format of the generated content.",
45+
"type": "string",
46+
"enum": ["text", "markdown", "html", "json", "code", "other"]
47+
},
48+
"tokens_used": {
49+
"description": "Total tokens used to produce this output, if available.",
50+
"type": "integer",
51+
"minimum": 0
52+
},
53+
"model_name": {
54+
"description": "Identifier for the model or engine used, if applicable.",
55+
"type": "string",
56+
"maxLength": 256
57+
},
58+
"choices": {
59+
"description": "Optional list of alternative generations (e.g., n-best samples).",
60+
"type": "array",
61+
"items": {
62+
"type": "object",
63+
"additionalProperties": false,
64+
"properties": {
65+
"content": {
66+
"description": "Alternative generated content.",
67+
"type": "string",
68+
"minLength": 1,
69+
"maxLength": 500000
70+
},
71+
"format": {
72+
"description": "Format of this alternative content.",
73+
"type": "string",
74+
"enum": ["text", "markdown", "html", "json", "code", "other"]
75+
},
76+
"rank": {
77+
"description": "Optional rank or ordering for this choice.",
78+
"type": "integer",
79+
"minimum": 0
80+
}
81+
},
82+
"required": ["content"]
83+
}
84+
}
85+
},
86+
"required": ["content"]
87+
},
88+
"usage": {
89+
"description": "Optional resource usage metrics for this invocation.",
90+
"type": "object",
91+
"additionalProperties": false,
92+
"properties": {
93+
"input_tokens": {
94+
"description": "Number of input tokens consumed.",
95+
"type": "integer",
96+
"minimum": 0
97+
},
98+
"output_tokens": {
99+
"description": "Number of output tokens produced.",
100+
"type": "integer",
101+
"minimum": 0
102+
},
103+
"total_tokens": {
104+
"description": "Total tokens used (input + output), if available.",
105+
"type": "integer",
106+
"minimum": 0
107+
},
108+
"cost_usd": {
109+
"description": "Optional cost for this call in USD (or equivalent fiat), if known.",
110+
"type": "number",
111+
"minimum": 0
112+
},
113+
"latency_ms": {
114+
"description": "Observed end-to-end latency for this invocation in milliseconds.",
115+
"type": "integer",
116+
"minimum": 0
117+
}
118+
}
119+
}
120+
},
121+
"required": ["x402", "trace", "status", "result"]
122+
}
123+
]
124+
}

‎schemas/v1.0.0/commons/generate/requests/generate.request.schema.json‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
{
2+
"$id": "https://commandlayer.org/schemas/v1.0.0/commons/generate/requests/generate.request.schema.json",
3+
"$schema": "https://json-schema.org/draft/2020-12/schema",
4+
"title": "generate.request",
5+
"description": "Request to generate content from a prompt and optional seed/context, with explicit limits, A2A-style channel metadata, optional auth, delegation, and context for multi-agent flows.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
9+
"properties": {
10+
"x402": {
11+
"description": "x402 envelope describing the verb, version, and optional routing metadata.",
12+
"allOf": [
13+
{
14+
"$ref": "https://commandlayer.org/schemas/v1.0.0/_shared/x402.schema.json"
15+
},
16+
{
17+
"type": "object",
18+
"additionalProperties": false,
19+
"properties": {
20+
"verb": { "const": "generate" },
21+
"version": { "const": "1.0.0" }
22+
},
23+
"required": ["verb", "version"]
24+
}
25+
]
26+
},
27+
28+
"actor": {
29+
"description": "Logical caller (wallet, ENS name, application, or agent identifier).",
30+
"type": "string",
31+
"minLength": 1,
32+
"maxLength": 256
33+
},
34+
35+
"limits": {
36+
"description": "Guardrails for output size and latency.",
37+
"type": "object",
38+
"additionalProperties": false,
39+
"properties": {
40+
"max_output_tokens": {
41+
"description": "Maximum tokens in the generated output.",
42+
"type": "integer",
43+
"minimum": 1,
44+
"maximum": 32768
45+
},
46+
"max_chars": {
47+
"description": "Maximum characters in the generated output.",
48+
"type": "integer",
49+
"minimum": 1,
50+
"maximum": 500000
51+
},
52+
"max_latency_ms": {
53+
"description": "Optional upper bound on end-to-end latency in milliseconds.",
54+
"type": "integer",
55+
"minimum": 1,
56+
"maximum": 600000
57+
}
58+
},
59+
"required": ["max_output_tokens"]
60+
},
61+
62+
"input": {
63+
"description": "Prompt and optional seed/content for generation.",
64+
"type": "object",
65+
"additionalProperties": false,
66+
"properties": {
67+
"prompt": {
68+
"description": "Natural-language or structured prompt describing what to generate.",
69+
"type": "string",
70+
"minLength": 1,
71+
"maxLength": 20000
72+
},
73+
"seed_content": {
74+
"description": "Optional seed text or markup to base the generation on.",
75+
"type": "string",
76+
"maxLength": 250000
77+
},
78+
"format": {
79+
"description": "Desired format of the generated content.",
80+
"type": "string",
81+
"enum": ["text", "markdown", "html", "json", "code", "other"]
82+
},
83+
"locale": {
84+
"description": "IETF BCP 47 language tag for the output (e.g., en-US).",
85+
"type": "string",
86+
"minLength": 2,
87+
"maxLength": 32
88+
},
89+
"style": {
90+
"description": "High-level style hint such as 'formal', 'informal', 'technical', 'marketing', or 'executive'.",
91+
"type": "string",
92+
"maxLength": 64
93+
},
94+
"tone": {
95+
"description": "Tone hint such as 'neutral', 'friendly', 'serious', 'playful'.",
96+
"type": "string",
97+
"maxLength": 64
98+
},
99+
"audience": {
100+
"description": "Intended audience (e.g., 'developers', 'executives', 'students').",
101+
"type": "string",
102+
"maxLength": 128
103+
},
104+
"temperature": {
105+
"description": "Sampling temperature hint in [0, 2].",
106+
"type": "number",
107+
"minimum": 0,
108+
"maximum": 2
109+
},
110+
"top_p": {
111+
"description": "Nucleus sampling top_p hint in (0, 1].",
112+
"type": "number",
113+
"minimum": 0,
114+
"maximum": 1
115+
},
116+
"stop": {
117+
"description": "Optional list of stop sequences.",
118+
"type": "array",
119+
"items": {
120+
"type": "string",
121+
"minLength": 1,
122+
"maxLength": 128
123+
},
124+
"maxItems": 16
125+
}
126+
},
127+
"required": ["prompt"]
128+
},
129+
130+
"channel": {
131+
"description": "A2A-style channel configuration describing how this request is transported.",
132+
"type": "object",
133+
"additionalProperties": false,
134+
"properties": {
135+
"protocol": {
136+
"description": "Underlying transport protocol.",
137+
"type": "string",
138+
"enum": ["https", "http", "websocket", "sse", "json-rpc", "queue"]
139+
},
140+
"input_modalities": {
141+
"description": "Modalities used for the request payload.",
142+
"type": "array",
143+
"items": {
144+
"type": "string",
145+
"enum": ["text", "markdown", "html", "json"]
146+
},
147+
"minItems": 1
148+
},
149+
"output_modalities": {
150+
"description": "Modalities expected in the response.",
151+
"type": "array",
152+
"items": {
153+
"type": "string",
154+
"enum": ["text", "markdown", "html", "json"]
155+
},
156+
"minItems": 1
157+
},
158+
"endpoint": {
159+
"description": "Concrete endpoint URI for this invocation (e.g., HTTPS URL, JSON-RPC endpoint).",
160+
"type": "string",
161+
"minLength": 1,
162+
"maxLength": 2048
163+
}
164+
},
165+
"required": ["protocol", "input_modalities", "output_modalities"]
166+
},
167+
168+
"auth": {
169+
"description": "Authentication metadata. Concrete credentials are implementation-specific and MUST NOT be logged in full.",
170+
"type": "object",
171+
"additionalProperties": false,
172+
"properties": {
173+
"scheme": {
174+
"description": "Auth scheme (e.g., none, api_key, oauth2, signed_message).",
175+
"type": "string",
176+
"enum": ["none", "api_key", "oauth2", "signed_message"]
177+
},
178+
"api_key_id": {
179+
"description": "Optional opaque identifier for the API key used.",
180+
"type": "string",
181+
"maxLength": 256
182+
},
183+
"oauth2_client_id": {
184+
"description": "Optional OAuth2 client identifier.",
185+
"type": "string",
186+
"maxLength": 256
187+
},
188+
"actor_wallet": {
189+
"description": "Optional EVM wallet address associated with this request.",
190+
"type": "string",
191+
"pattern": "^0x[a-fA-F0-9]{40}$"
192+
},
193+
"signature": {
194+
"description": "Optional detached signature (e.g., EIP-191) proving possession or intent.",
195+
"type": "string",
196+
"maxLength": 4096
197+
}
198+
}
199+
},
200+
201+
"delegation": {
202+
"description": "Swarm-style delegation policy for multi-agent flows (e.g., handoff to specialized generators or post-processors).",
203+
"type": "object",
204+
"additionalProperties": false,
205+
"properties": {
206+
"allowed": {
207+
"description": "Whether the agent is allowed to hand off or delegate this request.",
208+
"type": "boolean"
209+
},
210+
"targets": {
211+
"description": "Preferred downstream agents (e.g., ENS names or canonical identifiers).",
212+
"type": "array",
213+
"items": {
214+
"type": "string",
215+
"minLength": 1,
216+
"maxLength": 256
217+
}
218+
},
219+
"policy": {
220+
"description": "Delegation policy.",
221+
"type": "string",
222+
"enum": ["auto", "manual", "none"]
223+
},
224+
"reason": {
225+
"description": "Human-readable reason or intent for allowing delegation.",
226+
"type": "string",
227+
"maxLength": 1024
228+
}
229+
}
230+
},
231+
232+
"context": {
233+
"description": "Optional conversation or workflow context for multi-step or multi-agent interactions.",
234+
"type": "object",
235+
"additionalProperties": false,
236+
"properties": {
237+
"conversation_id": {
238+
"description": "Logical conversation identifier.",
239+
"type": "string",
240+
"maxLength": 256
241+
},
242+
"parent_task_id": {
243+
"description": "Identifier of the parent task, if this request is part of a larger workflow.",
244+
"type": "string",
245+
"maxLength": 256
246+
},
247+
"thread": {
248+
"description": "Minimal structured history; format is intentionally implementation-defined.",
249+
"type": "array",
250+
"items": {
251+
"type": "object"
252+
}
253+
}
254+
}
255+
},
256+
257+
"metadata": {
258+
"description": "Non-normative metadata for routing, billing, or analytics. MUST NOT change the core semantics of the request.",
259+
"type": "object",
260+
"additionalProperties": true
261+
}
262+
},
263+
264+
"required": ["x402", "actor", "limits", "input", "channel"]
265+
}

0 commit comments

Comments
 (0)