@ego-z/contracts 0.15.18 → 0.15.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/src/ask.d.ts +5 -3
- package/src/index.d.ts +4 -0
- package/src/project-file.d.ts +354 -0
package/package.json
CHANGED
package/src/ask.d.ts
CHANGED
|
@@ -530,8 +530,9 @@ export type AutoTier = 'light' | 'default' | 'heavy';
|
|
|
530
530
|
*/
|
|
531
531
|
export interface AskRouting {
|
|
532
532
|
/**
|
|
533
|
-
* The tier Auto picked. A conversation keeps the highest tier
|
|
534
|
-
*
|
|
533
|
+
* The tier Auto picked. A conversation keeps the highest tier Auto has
|
|
534
|
+
* judged it at, so a later turn never gets a lower one — except after a
|
|
535
|
+
* `fallback`, which the conversation doesn't keep.
|
|
535
536
|
*/
|
|
536
537
|
tier: AutoTier;
|
|
537
538
|
/**
|
|
@@ -540,7 +541,8 @@ export interface AskRouting {
|
|
|
540
541
|
* - `sticky`: the conversation was already at a higher tier, and the turn
|
|
541
542
|
* kept it (at `heavy`, Auto stops judging);
|
|
542
543
|
* - `fallback`: Auto couldn't judge this turn in time, so it ran at
|
|
543
|
-
* `default`.
|
|
544
|
+
* `default`. The conversation keeps its tier, so the next turn can get
|
|
545
|
+
* a lower one.
|
|
544
546
|
*/
|
|
545
547
|
source: 'classifier' | 'sticky' | 'fallback';
|
|
546
548
|
/**
|
package/src/index.d.ts
CHANGED
|
@@ -83,6 +83,9 @@
|
|
|
83
83
|
* `UpdateUserMemoryFactBody`, list / detail / fact /
|
|
84
84
|
* forget response data, vocabularies (`UserMemoryKind`,
|
|
85
85
|
* `UserMemoryStatus`, `UserMemorySource`).
|
|
86
|
+
* - `project-file.d.ts` — the `.egoz` project file and its export /
|
|
87
|
+
* import routes: `EgozProjectFile` and its sections,
|
|
88
|
+
* `ProjectFileImportBody`, `ProjectFileImportResult`.
|
|
86
89
|
*
|
|
87
90
|
* This barrel re-exports everything so existing consumers' import paths
|
|
88
91
|
* (`import type { AskResponseData } from '@ego-z/contracts'`) keep
|
|
@@ -112,3 +115,4 @@ export * from './personality';
|
|
|
112
115
|
export * from './user-memory';
|
|
113
116
|
export * from './search';
|
|
114
117
|
export * from './controlled';
|
|
118
|
+
export * from './project-file';
|
|
@@ -0,0 +1,354 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @ego-z/contracts — the `.egoz` project file, and the routes that make and
|
|
3
|
+
* read it.
|
|
4
|
+
*
|
|
5
|
+
* - `GET /egoz/tenants/:tenantId/project-file` → `ProjectFileExportResponseData`
|
|
6
|
+
* - `POST /egoz/tenants/:tenantId/project-file/import` ← `ProjectFileImportBody`
|
|
7
|
+
* → `ProjectFileImportResult`
|
|
8
|
+
* - `GET /egoz/mcp-admin/project-file` (same, for an MCP token's project)
|
|
9
|
+
* - `POST /egoz/mcp-admin/project-file/import` (same, plus `force`)
|
|
10
|
+
*
|
|
11
|
+
* A `.egoz` file is everything an owner built in a project — settings,
|
|
12
|
+
* prompts, personalities, tools, knowledge base, prices, extensions and web
|
|
13
|
+
* search sites — as JSON. Importing it into another project makes that
|
|
14
|
+
* project's build match the file, one to one.
|
|
15
|
+
*
|
|
16
|
+
* ── What a file never holds ──────────────────────────────────────────────
|
|
17
|
+
*
|
|
18
|
+
* Tokens: API keys, MCP tokens, provider keys, the webhook secret, and the
|
|
19
|
+
* value of every tool header whose name looks like a credential
|
|
20
|
+
* (`Authorization`, `Cookie`, or any name containing `token`, `secret`,
|
|
21
|
+
* `key`, `auth`, `password` or `credential`). Those headers keep their name
|
|
22
|
+
* in `ProjectFileTool.secretHeaders`. A credential written anywhere else —
|
|
23
|
+
* inside an endpoint URL, a description, a document — is not recognised and
|
|
24
|
+
* is exported as written.
|
|
25
|
+
*
|
|
26
|
+
* Nor what a project collected while running: conversations, traces,
|
|
27
|
+
* analytics, learned facts, incidents, alerts. Nor the project itself: its
|
|
28
|
+
* name, compliance settings, plan and integration scope stay the project's
|
|
29
|
+
* own.
|
|
30
|
+
*
|
|
31
|
+
* ── Sections ─────────────────────────────────────────────────────────────
|
|
32
|
+
*
|
|
33
|
+
* Every section is optional. On import, a section the file leaves out leaves
|
|
34
|
+
* that part of the project as it is; a section the file has — even an empty
|
|
35
|
+
* one — replaces that part, so an empty `tools: []` deletes every tool. An
|
|
36
|
+
* export always writes every section, except `webSearchSites` when the search
|
|
37
|
+
* service could not be read.
|
|
38
|
+
*
|
|
39
|
+
* ── Versioning ───────────────────────────────────────────────────────────
|
|
40
|
+
*
|
|
41
|
+
* `version` changes only when an existing field changes meaning. New fields
|
|
42
|
+
* are added within a version, and an import treats a setting missing from an
|
|
43
|
+
* older file as that setting's default.
|
|
44
|
+
*/
|
|
45
|
+
|
|
46
|
+
import type { PersonalityTraitsWire } from './personality';
|
|
47
|
+
import type { OrchestrationMode, TenantScope } from './tenant';
|
|
48
|
+
import type { VerifyMode } from './controlled';
|
|
49
|
+
import type { JsonSchemaWire, ToolAuthType, ToolHttpMethod, ToolType } from './tool';
|
|
50
|
+
import type { RagDocumentSourceType } from './rag';
|
|
51
|
+
|
|
52
|
+
// ============================================================================
|
|
53
|
+
// The file
|
|
54
|
+
// ============================================================================
|
|
55
|
+
|
|
56
|
+
/** The contents of a `.egoz` file. */
|
|
57
|
+
export interface EgozProjectFile {
|
|
58
|
+
/** Always `"egoz.project"`. */
|
|
59
|
+
format: 'egoz.project';
|
|
60
|
+
/** File format version. Files made today are version 1. */
|
|
61
|
+
version: 1;
|
|
62
|
+
/** When the file was made, ISO 8601. */
|
|
63
|
+
exportedAt: string;
|
|
64
|
+
/** The project the file was made from. Read-only information. */
|
|
65
|
+
exportedFrom: ProjectFileOrigin;
|
|
66
|
+
|
|
67
|
+
config?: ProjectFileConfig;
|
|
68
|
+
prompts?: ProjectFilePrompts;
|
|
69
|
+
personalities?: ProjectFilePersonality[];
|
|
70
|
+
tools?: ProjectFileTool[];
|
|
71
|
+
/** Knowledge-base documents, oldest first. */
|
|
72
|
+
knowledgeBase?: ProjectFileDocument[];
|
|
73
|
+
/** Per-project price overrides. EgoZ's default prices are not included. */
|
|
74
|
+
pricing?: ProjectFilePricing[];
|
|
75
|
+
/** Extensions this project has turned on or configured. */
|
|
76
|
+
extensions?: ProjectFileExtension[];
|
|
77
|
+
/** The sites `web_search` answers from when `config.webSearchScope` is `"whitelist"`. */
|
|
78
|
+
webSearchSites?: string[];
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Where a file came from. Import never writes any of it. */
|
|
82
|
+
export interface ProjectFileOrigin {
|
|
83
|
+
projectId: string;
|
|
84
|
+
name: string;
|
|
85
|
+
slug: string;
|
|
86
|
+
/**
|
|
87
|
+
* The source project's integration scope. Not imported — a project's
|
|
88
|
+
* scope is its own — but an import warns when it differs, because a
|
|
89
|
+
* gateway's learned facts must not be read as one customer's.
|
|
90
|
+
*/
|
|
91
|
+
tenantScope: TenantScope;
|
|
92
|
+
/**
|
|
93
|
+
* Whether the source project signed its tool calls with a webhook secret.
|
|
94
|
+
* The secret itself is never in the file; an import into a project
|
|
95
|
+
* without one says so, since a backend that checks signatures would then
|
|
96
|
+
* reject every call.
|
|
97
|
+
*/
|
|
98
|
+
signsToolCalls: boolean;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
// ============================================================================
|
|
102
|
+
// Sections
|
|
103
|
+
// ============================================================================
|
|
104
|
+
|
|
105
|
+
/** A provider + model pair, as on the switchable-model menu. */
|
|
106
|
+
export interface ProjectFileModelRef {
|
|
107
|
+
provider: string;
|
|
108
|
+
model: string;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* The project's settings, as stored — `null` means "EgoZ's default", so a
|
|
113
|
+
* project that never picked a model keeps following the default after import.
|
|
114
|
+
*
|
|
115
|
+
* Over MCP, an import leaves `llmProviderEndpoint`, `llmProviderApiVersion`,
|
|
116
|
+
* `embeddingProviderEndpoint` and `authCallbackUrl` as the project has them
|
|
117
|
+
* (a person sets those in the Console), and refuses a file whose
|
|
118
|
+
* `llmProvider` or `embeddingProvider` differs from the project's.
|
|
119
|
+
*/
|
|
120
|
+
export interface ProjectFileConfig {
|
|
121
|
+
llmProvider: 'openai' | 'azure_openai' | 'anthropic' | 'gemini' | 'bedrock' | 'openrouter' | 'custom_openai_compat';
|
|
122
|
+
llmProviderEndpoint: string | null;
|
|
123
|
+
llmProviderApiVersion: string | null;
|
|
124
|
+
/** `null` = the chat provider also embeds. */
|
|
125
|
+
embeddingProvider: 'openai' | 'azure_openai' | 'cohere' | 'voyage' | 'gemini' | 'bedrock' | null;
|
|
126
|
+
embeddingProviderEndpoint: string | null;
|
|
127
|
+
model: string | null;
|
|
128
|
+
embeddingModel: string | null;
|
|
129
|
+
|
|
130
|
+
modelSwitchingEnabled: boolean;
|
|
131
|
+
allowedModels: ProjectFileModelRef[];
|
|
132
|
+
autoMode: 'off' | 'available' | 'default';
|
|
133
|
+
autoShadow: boolean;
|
|
134
|
+
autoLightModel: ProjectFileModelRef | null;
|
|
135
|
+
autoHeavyModel: ProjectFileModelRef | null;
|
|
136
|
+
|
|
137
|
+
temperature: number;
|
|
138
|
+
maxTokens: number | null;
|
|
139
|
+
responseFormat: 'text' | 'json_object';
|
|
140
|
+
historyLength: number;
|
|
141
|
+
orchestrationMode: OrchestrationMode;
|
|
142
|
+
assistModel: string | null;
|
|
143
|
+
verifyMode: VerifyMode;
|
|
144
|
+
verifyThreshold: number;
|
|
145
|
+
|
|
146
|
+
toolsEnabled: boolean;
|
|
147
|
+
ragEnabled: boolean;
|
|
148
|
+
retryAttempts: number;
|
|
149
|
+
retryDelayMs: number;
|
|
150
|
+
authCallbackUrl: string | null;
|
|
151
|
+
toolBaseUrl: string | null;
|
|
152
|
+
|
|
153
|
+
generateConversationTitle: boolean;
|
|
154
|
+
persistMessageContent: boolean;
|
|
155
|
+
learningEnabled: boolean;
|
|
156
|
+
learningRetentionDays: number;
|
|
157
|
+
|
|
158
|
+
webAccessEnabled: boolean;
|
|
159
|
+
webSearchScope: 'global' | 'whitelist';
|
|
160
|
+
webSearchMaxCallsPerTurn: number;
|
|
161
|
+
webFetchMaxCallsPerTurn: number;
|
|
162
|
+
|
|
163
|
+
voiceEnabled: boolean;
|
|
164
|
+
voiceModel: string | null;
|
|
165
|
+
voiceTtsVoice: string | null;
|
|
166
|
+
voiceMinuteLimit: number | null;
|
|
167
|
+
voiceSttVendor: 'openai' | 'deepgram' | null;
|
|
168
|
+
voiceTtsVendor: 'openai' | 'elevenlabs' | null;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** The project's own system prompts. `null` = EgoZ's default prompt. */
|
|
172
|
+
export interface ProjectFilePrompts {
|
|
173
|
+
base: string | null;
|
|
174
|
+
rag: string | null;
|
|
175
|
+
tool: string | null;
|
|
176
|
+
ragTool: string | null;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** A project personality profile. */
|
|
180
|
+
export interface ProjectFilePersonality {
|
|
181
|
+
name: string;
|
|
182
|
+
traits: PersonalityTraitsWire;
|
|
183
|
+
customInstructions: string | null;
|
|
184
|
+
exampleResponses: string[];
|
|
185
|
+
avoidPhrases: string[];
|
|
186
|
+
preferredPhrases: string[];
|
|
187
|
+
agentName: string | null;
|
|
188
|
+
agentRole: string | null;
|
|
189
|
+
agentTone: string | null;
|
|
190
|
+
/** The profile `/ask` uses. At most one per file. */
|
|
191
|
+
isActive: boolean;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/** A tool definition. */
|
|
195
|
+
export interface ProjectFileTool {
|
|
196
|
+
toolName: string;
|
|
197
|
+
toolDescription: string;
|
|
198
|
+
apiEndpoint: string;
|
|
199
|
+
toolType: ToolType;
|
|
200
|
+
httpMethod: ToolHttpMethod;
|
|
201
|
+
inputSchema: JsonSchemaWire;
|
|
202
|
+
outputSchema: JsonSchemaWire;
|
|
203
|
+
/** Static headers, without the ones in `secretHeaders`. */
|
|
204
|
+
headers: Record<string, string>;
|
|
205
|
+
/**
|
|
206
|
+
* Static headers whose value was left out because the name looks like a
|
|
207
|
+
* credential. On import each takes the value the project's tool of the
|
|
208
|
+
* same name already has; one the project doesn't have is reported, and
|
|
209
|
+
* the tool is saved without it until someone enters it.
|
|
210
|
+
*/
|
|
211
|
+
secretHeaders: string[];
|
|
212
|
+
authType: ToolAuthType;
|
|
213
|
+
retryAttempts: number;
|
|
214
|
+
retryDelayMs: number;
|
|
215
|
+
enabled: boolean;
|
|
216
|
+
gqlQuery: string | null;
|
|
217
|
+
exampleInput: Record<string, unknown> | null;
|
|
218
|
+
exampleOutput: Record<string, unknown> | null;
|
|
219
|
+
forwardHeaders: string[];
|
|
220
|
+
maxCallsPerTurn: number;
|
|
221
|
+
successPath: string | null;
|
|
222
|
+
displayPath: string | null;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** A knowledge-base document. Imported documents are indexed again in the new project. */
|
|
226
|
+
export interface ProjectFileDocument {
|
|
227
|
+
title: string;
|
|
228
|
+
content: string;
|
|
229
|
+
sourceType: RagDocumentSourceType;
|
|
230
|
+
sourceUrl: string | null;
|
|
231
|
+
tags: string[];
|
|
232
|
+
metadata: Record<string, unknown>;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/** A per-project price, USD per 1M tokens. */
|
|
236
|
+
export interface ProjectFilePricing {
|
|
237
|
+
provider: string;
|
|
238
|
+
model: string;
|
|
239
|
+
promptPerM: number;
|
|
240
|
+
completionPerM: number;
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/**
|
|
244
|
+
* An extension's state. `config` is what the project set, without the
|
|
245
|
+
* extension's defaults, so a later change to a default still applies.
|
|
246
|
+
*/
|
|
247
|
+
export interface ProjectFileExtension {
|
|
248
|
+
extensionId: string;
|
|
249
|
+
enabled: boolean;
|
|
250
|
+
config: Record<string, unknown>;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
// ============================================================================
|
|
254
|
+
// Export
|
|
255
|
+
// ============================================================================
|
|
256
|
+
|
|
257
|
+
/** `data` of `GET .../project-file`. */
|
|
258
|
+
export interface ProjectFileExportResponseData {
|
|
259
|
+
/** Save this as `<slug>.egoz`. */
|
|
260
|
+
file: EgozProjectFile;
|
|
261
|
+
/** What the file couldn't include, e.g. web search sites while the search service is down. */
|
|
262
|
+
warnings: string[];
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
// ============================================================================
|
|
266
|
+
// Import
|
|
267
|
+
// ============================================================================
|
|
268
|
+
|
|
269
|
+
/** Body of `POST .../project-file/import`. */
|
|
270
|
+
export interface ProjectFileImportBody {
|
|
271
|
+
/** The parsed contents of a `.egoz` file. */
|
|
272
|
+
file: EgozProjectFile;
|
|
273
|
+
/** Work out and return what the import would change, and change nothing. */
|
|
274
|
+
dryRun?: boolean;
|
|
275
|
+
/**
|
|
276
|
+
* MCP only. Allows the import to overwrite or delete things a person
|
|
277
|
+
* made in the Console (`ProjectFileImportResult.manualChanges`).
|
|
278
|
+
*/
|
|
279
|
+
force?: boolean;
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/** What an import changed, or — on a dry run — would change. */
|
|
283
|
+
export interface ProjectFileImportResult {
|
|
284
|
+
dryRun: boolean;
|
|
285
|
+
/** True once the changes are saved. Always false on a dry run. */
|
|
286
|
+
applied: boolean;
|
|
287
|
+
/**
|
|
288
|
+
* Problems that stop the import, e.g. a knowledge base bigger than this
|
|
289
|
+
* project's plan allows. A dry run returns them; a real import with any
|
|
290
|
+
* is refused.
|
|
291
|
+
*/
|
|
292
|
+
errors: string[];
|
|
293
|
+
warnings: string[];
|
|
294
|
+
sections: ProjectFileImportSections;
|
|
295
|
+
/**
|
|
296
|
+
* How many things a person made in the Console the import overwrites or
|
|
297
|
+
* deletes. Over MCP, any at all needs `force: true`.
|
|
298
|
+
*/
|
|
299
|
+
manualChanges: number;
|
|
300
|
+
/** What's left to do by hand for the project to work like the original. */
|
|
301
|
+
followUps: ProjectFileFollowUp[];
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/** Per-section changes. Names are tool names, document titles, `provider/model`, URLs… */
|
|
305
|
+
export interface ProjectFileSectionChanges {
|
|
306
|
+
/** False when the file leaves this section out; the project's own is kept. */
|
|
307
|
+
included: boolean;
|
|
308
|
+
created: string[];
|
|
309
|
+
updated: string[];
|
|
310
|
+
deleted: string[];
|
|
311
|
+
unchanged: number;
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
export interface ProjectFileImportSections {
|
|
315
|
+
config: ProjectFileConfigChanges;
|
|
316
|
+
prompts: ProjectFileSectionChanges;
|
|
317
|
+
personalities: ProjectFileSectionChanges;
|
|
318
|
+
tools: ProjectFileSectionChanges;
|
|
319
|
+
knowledgeBase: ProjectFileSectionChanges;
|
|
320
|
+
pricing: ProjectFileSectionChanges;
|
|
321
|
+
extensions: ProjectFileSectionChanges;
|
|
322
|
+
webSearchSites: ProjectFileSectionChanges;
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
export interface ProjectFileConfigChanges {
|
|
326
|
+
included: boolean;
|
|
327
|
+
/** Settings whose value changes. */
|
|
328
|
+
changed: string[];
|
|
329
|
+
/** Settings the file has a different value for that stay as they are (MCP: Console-only settings). */
|
|
330
|
+
kept: string[];
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
/** One thing to do after an import. */
|
|
334
|
+
export interface ProjectFileFollowUp {
|
|
335
|
+
kind: ProjectFileFollowUpKind;
|
|
336
|
+
/** What to do, in a sentence. */
|
|
337
|
+
message: string;
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
/**
|
|
341
|
+
* - `provider_key` — the imported settings use a provider this project has no key for.
|
|
342
|
+
* - `tool_secret` — a tool header the file left out, which this project's tool didn't have either.
|
|
343
|
+
* - `webhook_secret` — the source signed tool calls; this project has no webhook secret.
|
|
344
|
+
* - `console_only` — MCP kept a setting a person sets in the Console.
|
|
345
|
+
* - `integration_scope` — the source's integration scope differs from this project's.
|
|
346
|
+
* - `web_search_sites` — sites that couldn't be synced with the search service.
|
|
347
|
+
*/
|
|
348
|
+
export type ProjectFileFollowUpKind =
|
|
349
|
+
| 'provider_key'
|
|
350
|
+
| 'tool_secret'
|
|
351
|
+
| 'webhook_secret'
|
|
352
|
+
| 'console_only'
|
|
353
|
+
| 'integration_scope'
|
|
354
|
+
| 'web_search_sites';
|