@fias/arche-sdk 1.1.8 → 1.2.0

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.
Files changed (7) hide show
  1. package/dist/types.d.ts +2 -0
  2. package/dist/types.d.ts.map +1 -1
  3. package/package.json +1 -1
  4. package/templates/default/AGENTS.md +43 -39
  5. package/templates/default/CLAUDE.md +43 -39
  6. package/templates/default/fias-plugin.json +1 -2
  7. package/templates/default/package.json +2 -0
package/dist/types.d.ts CHANGED
@@ -88,6 +88,8 @@ export interface EntityInvocationParams {
88
88
  entityId: string;
89
89
  input: string;
90
90
  parameters?: Record<string, unknown>;
91
+ /** System prompt to send to the AI model. The arche/plugin provides context; the entity provides the capability. */
92
+ systemPrompt?: string;
91
93
  }
92
94
  /**
93
95
  * Navigation API available via useFiasNavigation() hook.
package/dist/types.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fias/arche-sdk",
3
- "version": "1.1.8",
3
+ "version": "1.2.0",
4
4
  "description": "SDK for building FIAS platform plugin arches",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
package/templates/default/AGENTS.md CHANGED
@@ -93,11 +93,13 @@ const files = await listFiles('data/'); // string[]
93
93
  await deleteFile('data/old.json');
94
94
  ```
95
95
 
96
- ### `useEntityInvocation()` — Invoke AI entities
96
+ ### `useEntityInvocation()` — Invoke AI models
97
97
 
98
98
  **Permission:** `entities:invoke`
99
99
  **Returns:** `EntityInvocationApi`
100
100
 
101
+ Entities are shared capabilities (model access). Your plugin provides the context (system prompt, input) at invoke time.
102
+
101
103
  ```tsx
102
104
  import { useEntityInvocation } from '@fias/arche-sdk';
103
105
 
@@ -105,7 +107,11 @@ function AISummarizer() {
105
107
  const { invoke, isLoading, result, error, streamingText } = useEntityInvocation();
106
108
 
107
109
  async function summarize(text: string) {
108
- await invoke({ entityId: 'ent_abc123', input: text });
110
+ await invoke({
111
+ entityId: 'ent_model_sonnet_45', // the AI model capability
112
+ input: text, // what to process
113
+ systemPrompt: 'You are a concise summarizer. Return a 2-3 sentence summary.',
114
+ });
109
115
  }
110
116
 
111
117
  return (
@@ -121,7 +127,7 @@ function AISummarizer() {
121
127
  }
122
128
  ```
123
129
 
124
- The `entityId` references a published entity on the platform. Browse available entities with `npx fias-dev entities`.
130
+ The `entityId` references a published model entity. Browse available models with `npx fias-dev entities`. The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
125
131
 
126
132
  ### `useFiasNavigation()` — In-plugin routing
127
133
 
@@ -178,38 +184,28 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
178
184
  "pricing": { "model": "free", "currency": "usd" },
179
185
  "permissions": ["theme:read", "entities:invoke"],
180
186
  "sdk": "^1.0.0",
181
- "dependencies": { "recharts": "2.15.0" },
182
- "aiConfigs": [
183
- {
184
- "configId": "summarizer",
185
- "label": "Text Summarizer",
186
- "entityId": "ent_abc123",
187
- "systemPrompt": "Summarize the input concisely.",
188
- "parameters": { "temperature": 0.3, "maxTokens": 500 }
189
- }
190
- ]
187
+ "dependencies": { "recharts": "2.15.0" }
191
188
  }
192
189
  ```
193
190
 
194
191
  **Fields:**
195
192
 
196
- | Field | Required | Description |
197
- | -------------- | -------- | --------------------------------------------- | ------- | --------- | ----------- |
198
- | `name` | Yes | Plugin identifier (lowercase, hyphens) |
199
- | `version` | Yes | Semver (e.g., `"1.0.0"`) |
200
- | `description` | Yes | Short marketplace description |
201
- | `main` | Yes | Entry point source file |
202
- | `archeType` | Yes | `"tool"` or `"site"` |
203
- | `tags` | No | Discovery tags |
204
- | `pricing` | Yes | `{ model: "free" | "fixed" | "per_use" | "tiered" }` |
205
- | `permissions` | Yes | Array of permission scopes |
206
- | `sdk` | Yes | SDK version range |
207
- | `dependencies` | No | npm packages with **exact** versions (max 20) |
208
- | `aiConfigs` | No | AI entity configurations (see below) |
193
+ | Field | Required | Description |
194
+ | -------------- | -------- | --------------------------------------------------------- |
195
+ | `name` | Yes | Plugin identifier (lowercase, hyphens) |
196
+ | `version` | Yes | Semver (e.g., `"1.0.0"`) |
197
+ | `description` | Yes | Short marketplace description |
198
+ | `main` | Yes | Entry point source file |
199
+ | `archeType` | Yes | `"tool"` or `"site"` |
200
+ | `tags` | No | Discovery tags |
201
+ | `pricing` | Yes | `{ model: "free" }` or `"fixed"`, `"per_use"`, `"tiered"` |
202
+ | `permissions` | Yes | Array of permission scopes |
203
+ | `sdk` | Yes | SDK version range |
204
+ | `dependencies` | No | npm packages with **exact** versions (max 20) |
209
205
 
210
206
  **Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`
211
207
 
212
- **AI Configs:** Declare entity invocations the plugin will use. Each config's `entityId` must reference a published prompt entity. Browse entities with `npx fias-dev entities`. Requires `entities:invoke` permission.
208
+ **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
213
209
 
214
210
  ## Plugin Constraints
215
211
 
@@ -259,25 +255,24 @@ These are hard limits enforced by the platform. Code that violates these will fa
259
255
  npx fias-dev login # Opens browser to sign in, saves API key automatically
260
256
  ```
261
257
 
262
- ### Step 2: Run the dev servers (two terminals)
258
+ This opens the FIAS platform in your browser. If you're already signed in, the API key is created and saved automatically. If not, you'll need to sign in (or sign up for a FIAS account if you don't have one — an invite code is required for new accounts). The URL is also printed in the terminal if the browser doesn't open automatically.
263
259
 
264
- ```bash
265
- # Terminal 1: Start plugin dev server (Vite, port 3100)
266
- npm run dev
260
+ ### Step 2: Start development
267
261
 
268
- # Terminal 2: Start dev harness with real AI (port 3200, uses credits)
269
- npm run dev:harness
262
+ ```bash
263
+ npm start # Starts both Vite + dev harness with real AI (uses credits)
270
264
  ```
271
265
 
272
- Open http://localhost:3200 in your browser. Entity invocations will use real AI models and deduct credits.
273
-
274
- For offline development without credits (AI calls return canned responses):
266
+ Or for offline development without credits (AI calls return canned responses):
275
267
 
276
268
  ```bash
277
- # Terminal 2 alternative: mock mode (no login needed, no credits)
278
- npm run dev:mock
269
+ npm run start:mock # Starts both Vite + dev harness with mock AI
279
270
  ```
280
271
 
272
+ Open http://localhost:3200 in your browser.
273
+
274
+ **Advanced:** If you prefer separate terminals, use `npm run dev` (Vite on port 3100) and `npm run dev:harness` or `npm run dev:mock` (harness on port 3200) independently.
275
+
281
276
  ### Browsing Available Entities
282
277
 
283
278
  ```bash
@@ -336,7 +331,16 @@ function AIChat() {
336
331
  return (
337
332
  <div>
338
333
  <textarea value={input} onChange={(e) => setInput(e.target.value)} />
339
- <button onClick={() => invoke({ entityId: 'ent_abc', input })} disabled={isLoading}>
334
+ <button
335
+ onClick={() =>
336
+ invoke({
337
+ entityId: 'ent_model_sonnet_45',
338
+ input,
339
+ systemPrompt: 'You are a helpful assistant.',
340
+ })
341
+ }
342
+ disabled={isLoading}
343
+ >
340
344
  Send
341
345
  </button>
342
346
  <div>{isLoading ? streamingText : result?.output}</div>
package/templates/default/CLAUDE.md CHANGED
@@ -93,11 +93,13 @@ const files = await listFiles('data/'); // string[]
93
93
  await deleteFile('data/old.json');
94
94
  ```
95
95
 
96
- ### `useEntityInvocation()` — Invoke AI entities
96
+ ### `useEntityInvocation()` — Invoke AI models
97
97
 
98
98
  **Permission:** `entities:invoke`
99
99
  **Returns:** `EntityInvocationApi`
100
100
 
101
+ Entities are shared capabilities (model access). Your plugin provides the context (system prompt, input) at invoke time.
102
+
101
103
  ```tsx
102
104
  import { useEntityInvocation } from '@fias/arche-sdk';
103
105
 
@@ -105,7 +107,11 @@ function AISummarizer() {
105
107
  const { invoke, isLoading, result, error, streamingText } = useEntityInvocation();
106
108
 
107
109
  async function summarize(text: string) {
108
- await invoke({ entityId: 'ent_abc123', input: text });
110
+ await invoke({
111
+ entityId: 'ent_model_sonnet_45', // the AI model capability
112
+ input: text, // what to process
113
+ systemPrompt: 'You are a concise summarizer. Return a 2-3 sentence summary.',
114
+ });
109
115
  }
110
116
 
111
117
  return (
@@ -121,7 +127,7 @@ function AISummarizer() {
121
127
  }
122
128
  ```
123
129
 
124
- The `entityId` references a published entity on the platform. Browse available entities with `npx fias-dev entities`.
130
+ The `entityId` references a published model entity. Browse available models with `npx fias-dev entities`. The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
125
131
 
126
132
  ### `useFiasNavigation()` — In-plugin routing
127
133
 
@@ -178,38 +184,28 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
178
184
  "pricing": { "model": "free", "currency": "usd" },
179
185
  "permissions": ["theme:read", "entities:invoke"],
180
186
  "sdk": "^1.0.0",
181
- "dependencies": { "recharts": "2.15.0" },
182
- "aiConfigs": [
183
- {
184
- "configId": "summarizer",
185
- "label": "Text Summarizer",
186
- "entityId": "ent_abc123",
187
- "systemPrompt": "Summarize the input concisely.",
188
- "parameters": { "temperature": 0.3, "maxTokens": 500 }
189
- }
190
- ]
187
+ "dependencies": { "recharts": "2.15.0" }
191
188
  }
192
189
  ```
193
190
 
194
191
  **Fields:**
195
192
 
196
- | Field | Required | Description |
197
- | -------------- | -------- | --------------------------------------------- | ------- | --------- | ----------- |
198
- | `name` | Yes | Plugin identifier (lowercase, hyphens) |
199
- | `version` | Yes | Semver (e.g., `"1.0.0"`) |
200
- | `description` | Yes | Short marketplace description |
201
- | `main` | Yes | Entry point source file |
202
- | `archeType` | Yes | `"tool"` or `"site"` |
203
- | `tags` | No | Discovery tags |
204
- | `pricing` | Yes | `{ model: "free" | "fixed" | "per_use" | "tiered" }` |
205
- | `permissions` | Yes | Array of permission scopes |
206
- | `sdk` | Yes | SDK version range |
207
- | `dependencies` | No | npm packages with **exact** versions (max 20) |
208
- | `aiConfigs` | No | AI entity configurations (see below) |
193
+ | Field | Required | Description |
194
+ | -------------- | -------- | --------------------------------------------------------- |
195
+ | `name` | Yes | Plugin identifier (lowercase, hyphens) |
196
+ | `version` | Yes | Semver (e.g., `"1.0.0"`) |
197
+ | `description` | Yes | Short marketplace description |
198
+ | `main` | Yes | Entry point source file |
199
+ | `archeType` | Yes | `"tool"` or `"site"` |
200
+ | `tags` | No | Discovery tags |
201
+ | `pricing` | Yes | `{ model: "free" }` or `"fixed"`, `"per_use"`, `"tiered"` |
202
+ | `permissions` | Yes | Array of permission scopes |
203
+ | `sdk` | Yes | SDK version range |
204
+ | `dependencies` | No | npm packages with **exact** versions (max 20) |
209
205
 
210
206
  **Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`
211
207
 
212
- **AI Configs:** Declare entity invocations the plugin will use. Each config's `entityId` must reference a published prompt entity. Browse entities with `npx fias-dev entities`. Requires `entities:invoke` permission.
208
+ **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
213
209
 
214
210
  ## Plugin Constraints
215
211
 
@@ -259,25 +255,24 @@ These are hard limits enforced by the platform. Code that violates these will fa
259
255
  npx fias-dev login # Opens browser to sign in, saves API key automatically
260
256
  ```
261
257
 
262
- ### Step 2: Run the dev servers (two terminals)
258
+ This opens the FIAS platform in your browser. If you're already signed in, the API key is created and saved automatically. If not, you'll need to sign in (or sign up for a FIAS account if you don't have one — an invite code is required for new accounts). The URL is also printed in the terminal if the browser doesn't open automatically.
263
259
 
264
- ```bash
265
- # Terminal 1: Start plugin dev server (Vite, port 3100)
266
- npm run dev
260
+ ### Step 2: Start development
267
261
 
268
- # Terminal 2: Start dev harness with real AI (port 3200, uses credits)
269
- npm run dev:harness
262
+ ```bash
263
+ npm start # Starts both Vite + dev harness with real AI (uses credits)
270
264
  ```
271
265
 
272
- Open http://localhost:3200 in your browser. Entity invocations will use real AI models and deduct credits.
273
-
274
- For offline development without credits (AI calls return canned responses):
266
+ Or for offline development without credits (AI calls return canned responses):
275
267
 
276
268
  ```bash
277
- # Terminal 2 alternative: mock mode (no login needed, no credits)
278
- npm run dev:mock
269
+ npm run start:mock # Starts both Vite + dev harness with mock AI
279
270
  ```
280
271
 
272
+ Open http://localhost:3200 in your browser.
273
+
274
+ **Advanced:** If you prefer separate terminals, use `npm run dev` (Vite on port 3100) and `npm run dev:harness` or `npm run dev:mock` (harness on port 3200) independently.
275
+
281
276
  ### Browsing Available Entities
282
277
 
283
278
  ```bash
@@ -336,7 +331,16 @@ function AIChat() {
336
331
  return (
337
332
  <div>
338
333
  <textarea value={input} onChange={(e) => setInput(e.target.value)} />
339
- <button onClick={() => invoke({ entityId: 'ent_abc', input })} disabled={isLoading}>
334
+ <button
335
+ onClick={() =>
336
+ invoke({
337
+ entityId: 'ent_model_sonnet_45',
338
+ input,
339
+ systemPrompt: 'You are a helpful assistant.',
340
+ })
341
+ }
342
+ disabled={isLoading}
343
+ >
340
344
  Send
341
345
  </button>
342
346
  <div>{isLoading ? streamingText : result?.output}</div>
package/templates/default/fias-plugin.json CHANGED
@@ -7,6 +7,5 @@
7
7
  "tags": [],
8
8
  "pricing": { "model": "free", "currency": "usd" },
9
9
  "permissions": ["theme:read"],
10
- "sdk": "^1.0.0",
11
- "aiConfigs": []
10
+ "sdk": "^1.0.0"
12
11
  }
package/templates/default/package.json CHANGED
@@ -3,6 +3,8 @@
3
3
  "version": "1.0.0",
4
4
  "private": true,
5
5
  "scripts": {
6
+ "start": "vite & sleep 2 && fias-dev --live",
7
+ "start:mock": "vite & sleep 2 && fias-dev",
6
8
  "dev": "vite",
7
9
  "build": "vite build",
8
10
  "validate": "tsc --noEmit",