@microsoft/rayfin-semantic-model-pack 1.0.0 → 1.1.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.
- package/CHANGELOG +4 -0
- package/README.md +21 -8
- package/{skills/analytics/kit → kit}/hooks/use-semantic-model-query.spec.ts +21 -2
- package/{skills/analytics/kit → kit}/hooks/use-semantic-model-query.ts +4 -9
- package/{skills/analytics/pack.json → pack.json} +0 -5
- package/package.json +3 -1
- package/skills/analytics/SKILL.md +9 -8
- package/skills/dax-authoring/SKILL.md +3 -5
- package/skills/analytics/kit/lib/connectors.ts +0 -94
- /package/{skills/analytics/kit → kit}/scripts/rayfin-connector.mjs +0 -0
- /package/{skills/analytics/kit → kit}/scripts/rayfin-connector.test.mjs +0 -0
- /package/{skills/analytics/kit → kit}/scripts/schema-sql-batch.test.mjs +0 -0
- /package/{skills/analytics/kit → kit}/scripts/schema-sql-cli.test.mjs +0 -0
- /package/{skills/analytics/kit → kit}/scripts/schema-sql.mjs +0 -0
- /package/{skills/analytics/kit → kit}/scripts/schema-sql.test.mjs +0 -0
- /package/{skills/analytics/kit → kit}/scripts/schema.mjs +0 -0
- /package/{skills/analytics/kit → kit}/scripts/schema.test.mjs +0 -0
package/CHANGELOG
CHANGED
|
@@ -5,6 +5,10 @@ All notable changes to `@microsoft/rayfin-semantic-model-pack` will be documente
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## 1.1.0 - 2026-11-05
|
|
9
|
+
|
|
10
|
+
- [Rayfin Packs] Update semantic-model and visuals packs with data-app template fixes
|
|
11
|
+
|
|
8
12
|
## 1.0.0 - Initial release
|
|
9
13
|
|
|
10
14
|
- Add the `analytics` capability pack and the `dax-authoring`, `query-design`, and `schema-discovery` skills.
|
package/README.md
CHANGED
|
@@ -8,39 +8,52 @@ Agent skills and starter code for Power BI semantic-model analytics in Rayfin ap
|
|
|
8
8
|
> **Purpose**: Capability pack that teaches a coding agent to query a Power BI semantic model from a Rayfin app: connect the model, discover its schema, write DAX, and shape queries for visuals.
|
|
9
9
|
> **Use when**: A Rayfin app template adds semantic-model analytics to an app.
|
|
10
10
|
> **Do NOT use when**: You need a runtime library (use `@microsoft/rayfin-connector-fabric-semanticmodel`), or charts and tables (use `@microsoft/rayfin-visuals-pack`).
|
|
11
|
-
> **Contents**: `skills/analytics`, `skills/dax-authoring`, `skills/query-design`, `skills/schema-discovery`
|
|
11
|
+
> **Contents**: `skills/analytics`, `skills/dax-authoring`, `skills/query-design`, `skills/schema-discovery`, plus the `analytics` install layer: `pack.json` and `kit/`
|
|
12
12
|
> **Install**: `npm install @microsoft/rayfin-semantic-model-pack`
|
|
13
13
|
|
|
14
14
|
## Contents
|
|
15
15
|
|
|
16
|
-
The package has no entry point.
|
|
17
|
-
|
|
16
|
+
The package has no entry point. It has two layers:
|
|
17
|
+
|
|
18
|
+
- `skills/` is the agent content. Each folder is one skill and maps 1:1 to
|
|
19
|
+
`.agents/skills/<name>/` in an app. This is what both app templates share.
|
|
20
|
+
- `pack.json` and `kit/` at the package root are the Rayfin Universal App's
|
|
21
|
+
install layer for the `analytics` skill, the one named in `pack.json`.
|
|
18
22
|
|
|
19
23
|
| Skill | Contents |
|
|
20
24
|
| --- | --- |
|
|
21
|
-
| `analytics` |
|
|
25
|
+
| `analytics` | Reading a semantic model from the app. Installed by the root `pack.json`, whose `kit/` holds the semantic-model query hook and the schema scripts |
|
|
22
26
|
| `dax-authoring` | Writing and testing DAX queries |
|
|
23
27
|
| `query-design` | Splitting work between DAX and TypeScript, including multi-grain and cross-highlight queries |
|
|
24
28
|
| `schema-discovery` | Exploring a model's tables, columns, measures, and relationships |
|
|
25
29
|
|
|
26
30
|
`pack.json` tells a template how to apply the pack, such as which dependencies
|
|
27
|
-
to add and which kit files to copy where.
|
|
28
|
-
|
|
29
|
-
template's
|
|
31
|
+
to add and which kit files to copy where. Its `copy` sources are relative to
|
|
32
|
+
the package root. The Rayfin Universal App applies it with
|
|
33
|
+
`npm run pack:add -- analytics`, and the copy targets assume that template's
|
|
34
|
+
layout.
|
|
30
35
|
|
|
31
36
|
## Usage
|
|
32
37
|
|
|
33
38
|
Resolve `@microsoft/rayfin-semantic-model-pack/package.json`, then copy each
|
|
34
39
|
`skills/<name>/` folder next to it into the app's `.agents/skills/<name>/`.
|
|
35
40
|
|
|
41
|
+
A template that applies packs with `npm run pack:add`, such as the Rayfin
|
|
42
|
+
Universal App, also copies `pack.json` and `kit/` into
|
|
43
|
+
`.agents/skills/<name>/`, where `<name>` is the `name` in `pack.json`. A
|
|
44
|
+
template without `pack:add` takes `skills/` and doesn't read `pack.json`.
|
|
45
|
+
|
|
36
46
|
## Key Constraints & Gotchas
|
|
37
47
|
|
|
38
48
|
- Apply the template's `connectors` pack first. It installs the
|
|
39
49
|
`@/lib/rayfin-client` that the kit imports.
|
|
40
50
|
- The skills link to `visuals` from `@microsoft/rayfin-visuals-pack`, and to
|
|
41
|
-
`app-design
|
|
51
|
+
`app-design` and `app-validation`, which the app template
|
|
42
52
|
provides.
|
|
43
53
|
- The schema scripts need Node.js 22.13 or later.
|
|
54
|
+
- A copier that takes only `skills/<name>/` folders leaves `analytics` without
|
|
55
|
+
its `pack.json`, so `npm run pack:add -- analytics` can't find it. The
|
|
56
|
+
Universal App's copier must also mount the root `pack.json` and `kit/`.
|
|
44
57
|
|
|
45
58
|
## Trademarks
|
|
46
59
|
|
|
@@ -177,7 +177,7 @@ describe('useSemanticModelQuery', () => {
|
|
|
177
177
|
expect(result.current.data).toBeUndefined();
|
|
178
178
|
});
|
|
179
179
|
|
|
180
|
-
it('
|
|
180
|
+
it('directs an unknown connector to the CLI registration flow', async () => {
|
|
181
181
|
// The proxy throws for a name with no config. Left untranslated that
|
|
182
182
|
// surfaces as a generic transport failure, sending the builder to look at
|
|
183
183
|
// Fabric instead of at their own registration.
|
|
@@ -186,7 +186,10 @@ describe('useSemanticModelQuery', () => {
|
|
|
186
186
|
const { result } = render();
|
|
187
187
|
|
|
188
188
|
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
189
|
-
expect(result.current.error?.message).
|
|
189
|
+
expect(result.current.error?.message).toBe(
|
|
190
|
+
`No connector named "model". Check that the name matches rayfin/rayfin.yml, ` +
|
|
191
|
+
`or add it with \`npx rayfin connector add\`.`
|
|
192
|
+
);
|
|
190
193
|
// The original is kept so the SDK's own code is still recoverable.
|
|
191
194
|
expect((result.current.error?.cause as { code?: string })?.code).toBe(
|
|
192
195
|
'UNKNOWN_CONNECTOR'
|
|
@@ -194,6 +197,22 @@ describe('useSemanticModelQuery', () => {
|
|
|
194
197
|
expect(executeQuery).not.toHaveBeenCalled();
|
|
195
198
|
});
|
|
196
199
|
|
|
200
|
+
it('gives the same CLI guidance when a connector lookup returns undefined', async () => {
|
|
201
|
+
connectors.model = undefined;
|
|
202
|
+
|
|
203
|
+
const { result } = render();
|
|
204
|
+
|
|
205
|
+
await waitFor(() => expect(result.current.error).toBeDefined());
|
|
206
|
+
expect(result.current.error?.message).toBe(
|
|
207
|
+
`No connector named "model". Check that the name matches rayfin/rayfin.yml, ` +
|
|
208
|
+
`or add it with \`npx rayfin connector add\`.`
|
|
209
|
+
);
|
|
210
|
+
expect(result.current.error?.cause).toBeUndefined();
|
|
211
|
+
expect(result.current.data).toBeUndefined();
|
|
212
|
+
expect(result.current.isLoading).toBe(false);
|
|
213
|
+
expect(executeQuery).not.toHaveBeenCalled();
|
|
214
|
+
});
|
|
215
|
+
|
|
197
216
|
it('says so when the app never wired ConnectorsRayfinClient', async () => {
|
|
198
217
|
// The base template builds a plain RayfinClient with no `connectors`, and no
|
|
199
218
|
// pack rewrites that file. Without this the first symptom is an unrelated
|
|
@@ -55,9 +55,8 @@ interface QueryState {
|
|
|
55
55
|
/** Message for a connector this app has not registered. Names the fix, not the symptom. */
|
|
56
56
|
function notRegistered(connection: string): string {
|
|
57
57
|
return (
|
|
58
|
-
`No connector named "${connection}".
|
|
59
|
-
`
|
|
60
|
-
`rayfin/rayfin.yml.`
|
|
58
|
+
`No connector named "${connection}". Check that the name matches rayfin/rayfin.yml, ` +
|
|
59
|
+
`or add it with \`npx rayfin connector add\`.`
|
|
61
60
|
);
|
|
62
61
|
}
|
|
63
62
|
|
|
@@ -79,12 +78,8 @@ async function executeSemanticModelQuery(
|
|
|
79
78
|
if (!connectors) {
|
|
80
79
|
throw new Error(
|
|
81
80
|
`This app's Rayfin client has no "connectors". ` +
|
|
82
|
-
`
|
|
83
|
-
`
|
|
84
|
-
`ConnectorsRayfinClient constructed with connectorConfigs and ` +
|
|
85
|
-
`connectorRuntimes from packages/frontend/src/lib/connectors.ts. ` +
|
|
86
|
-
`See step 1 of the ` +
|
|
87
|
-
`analytics skill.`
|
|
81
|
+
`Run \`npm run pack:add -- connectors\` to build ` +
|
|
82
|
+
`ConnectorsRayfinClient. See step 1 of the analytics skill.`
|
|
88
83
|
);
|
|
89
84
|
}
|
|
90
85
|
|
|
@@ -24,11 +24,6 @@
|
|
|
24
24
|
"gitignore": [".schema/", ".rayfin-schema-query-*/"],
|
|
25
25
|
"copy": [
|
|
26
26
|
{ "from": "kit/hooks", "to": "packages/frontend/src/hooks" },
|
|
27
|
-
{
|
|
28
|
-
"from": "kit/lib/connectors.ts",
|
|
29
|
-
"to": "packages/frontend/src/lib/connectors.ts",
|
|
30
|
-
"initializationOnly": true
|
|
31
|
-
},
|
|
32
27
|
{
|
|
33
28
|
"from": "kit/scripts/rayfin-connector.mjs",
|
|
34
29
|
"to": "scripts/rayfin-connector.mjs",
|
package/package.json
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@microsoft/rayfin-semantic-model-pack",
|
|
3
3
|
"description": "Agent skills and starter code for Power BI semantic-model analytics in Rayfin apps",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.1.0",
|
|
5
5
|
"author": "Microsoft",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"files": [
|
|
9
|
+
"pack.json",
|
|
10
|
+
"kit",
|
|
9
11
|
"skills",
|
|
10
12
|
"CHANGELOG",
|
|
11
13
|
"LICENSE"
|
|
@@ -38,8 +38,9 @@ Analytics does not pull it in, because reading a model and drawing one are
|
|
|
38
38
|
separate jobs — an app that shows a handful of figures needs no chart library.
|
|
39
39
|
Most dashboards want both.
|
|
40
40
|
|
|
41
|
-
Re-applying either is safe:
|
|
42
|
-
|
|
41
|
+
Re-applying either is safe: existing files are preserved, not overwritten.
|
|
42
|
+
The connectors pack and `rayfin connector add` own `connectors.ts`; analytics
|
|
43
|
+
does not install a competing copy.
|
|
43
44
|
|
|
44
45
|
The analytics pack can also install a local semantic-model catalog. It is a
|
|
45
46
|
preview capability and ships off, so `schema:sql` exists only in an app that
|
|
@@ -84,7 +85,6 @@ Each row is a sibling skill:
|
|
|
84
85
|
| [`query-design`](../query-design/SKILL.md) | The dashboard needs more than one grain, or you are shaping a query for several visuals |
|
|
85
86
|
| [`visuals`](../visuals/SKILL.md) | You are building any chart, or configuring `DataGrid` |
|
|
86
87
|
| [`app-design`](../app-design/SKILL.md) | You are deciding layout and theming |
|
|
87
|
-
| [`fabric-sdk`](../fabric-sdk/SKILL.md) | Reference material for the CLI and the runtime client |
|
|
88
88
|
|
|
89
89
|
Each of those has a `references/` folder that is deliberately not required
|
|
90
90
|
reading; open a reference when the SKILL.md points you at it for the specific
|
|
@@ -302,7 +302,11 @@ function RevenueByRegionChart() {
|
|
|
302
302
|
}
|
|
303
303
|
```
|
|
304
304
|
|
|
305
|
+
**Runtime client:** `getRayfinClient()` is asynchronous in this template.
|
|
306
|
+
Always await it before reading `.connectors`.
|
|
307
|
+
|
|
305
308
|
**Caching:** There is none. Every call to `useSemanticModelQuery` reaches Power BI.
|
|
309
|
+
The hook's `refetch()` re-runs the current query.
|
|
306
310
|
If a screen re-queries more than you want, hold the result in state or memoize at
|
|
307
311
|
the call site — do not reintroduce a shared cache here without a per-principal key
|
|
308
312
|
and a TTL, because a process-global one serves another user's rows after a sign-in
|
|
@@ -315,8 +319,8 @@ reads only one renders nothing for half its failures.
|
|
|
315
319
|
auth. It is the original error, so its status and service code survive. `data`
|
|
316
320
|
is cleared when this is set.
|
|
317
321
|
- `data.status === "error"` carries what Power BI **returned**, already
|
|
318
|
-
categorised by the connector as `"query"` (bad DAX), `"overflow"` (
|
|
319
|
-
|
|
322
|
+
categorised by the connector as `"query"` (bad DAX), `"overflow"` (a numeric
|
|
323
|
+
value too large for a JavaScript number), `"api"` (dataset-level or auth), or `"network"`.
|
|
320
324
|
`error` stays `undefined` for these, so the category is always reachable.
|
|
321
325
|
|
|
322
326
|
Check both, in either order; they never both apply. Then check `data.status`
|
|
@@ -325,9 +329,6 @@ before reading `data.table`.
|
|
|
325
329
|
Retry only a known transient network or service-starting condition, and cap the attempts.
|
|
326
330
|
Authentication, permission, connector configuration, and query errors are permanent until something changes, so surface them immediately.
|
|
327
331
|
|
|
328
|
-
For the connector client, the response shapes, and advanced query options, refer to
|
|
329
|
-
the [fabric-sdk](../fabric-sdk/SKILL.md) skill.
|
|
330
|
-
|
|
331
332
|
### 6. Final validation
|
|
332
333
|
|
|
333
334
|
Follow the [app-validation](../app-validation/SKILL.md) skill to
|
|
@@ -154,11 +154,9 @@ field to the input envelope:
|
|
|
154
154
|
{ "query": "EVALUATE Sales", "resultSetRowCountLimit": 500 }
|
|
155
155
|
```
|
|
156
156
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
complete-looking partial answer. A value that is not a positive integer is
|
|
161
|
-
dropped silently and the query runs unbounded.
|
|
157
|
+
`resultSetRowCountLimit` silently truncates, so a result with exactly that many rows may be incomplete. `withValidatedRowLimit` silently drops values that are not positive integers, leaving no explicit `resultSetRowCountLimit` on the request.
|
|
158
|
+
|
|
159
|
+
An `overflow` error is separate: `toQueryResult` uses this category for per-table errors, including the observed case of a numeric value too large for a JavaScript number. It means a failed query result, never that `resultSetRowCountLimit` was hit.
|
|
162
160
|
|
|
163
161
|
## Troubleshooting
|
|
164
162
|
|
|
@@ -1,94 +0,0 @@
|
|
|
1
|
-
//-----------------------------------------------------------------------
|
|
2
|
-
// <copyright company="Microsoft Corporation">
|
|
3
|
-
// Copyright (c) Microsoft Corporation. All rights reserved.
|
|
4
|
-
// Licensed under the MIT license. See LICENSE file in the project root for full license information.
|
|
5
|
-
// </copyright>
|
|
6
|
-
//-----------------------------------------------------------------------
|
|
7
|
-
|
|
8
|
-
import type {
|
|
9
|
-
ConnectorConfig,
|
|
10
|
-
ConnectorsRuntime,
|
|
11
|
-
} from '@microsoft/rayfin-connectors';
|
|
12
|
-
import type { FabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
|
|
13
|
-
|
|
14
|
-
/**
|
|
15
|
-
* Connectors this app can talk to, keyed by the connector name declared in
|
|
16
|
-
* `rayfin/rayfin.yml` under `connectors[].name`.
|
|
17
|
-
*
|
|
18
|
-
* The index signature keeps every name usable without editing this file each
|
|
19
|
-
* time you run `rayfin connector add`. Narrow it to the names you actually use
|
|
20
|
-
* if you want the compiler to catch a typo in a connection alias:
|
|
21
|
-
*
|
|
22
|
-
* @example
|
|
23
|
-
* export type AppConnectorsSchema = {
|
|
24
|
-
* salesModel: FabricSemanticModel<'executeQuery'>;
|
|
25
|
-
* };
|
|
26
|
-
*/
|
|
27
|
-
export type AppConnectorsSchema = Record<
|
|
28
|
-
string,
|
|
29
|
-
FabricSemanticModel<'executeQuery'>
|
|
30
|
-
>;
|
|
31
|
-
|
|
32
|
-
/**
|
|
33
|
-
* Routing config for each connector, keyed by the same name again.
|
|
34
|
-
*
|
|
35
|
-
* `rayfin connector add` writes a `connectorConfig` constant into
|
|
36
|
-
* `rayfin/connectors/<name>/schema.ts`. Re-export that constant here rather
|
|
37
|
-
* than hand-writing the object, so this file cannot drift from `rayfin.yml`.
|
|
38
|
-
*
|
|
39
|
-
* @example
|
|
40
|
-
* import { connectorConfig as salesModel } from '../../../../rayfin/connectors/salesModel/schema';
|
|
41
|
-
*
|
|
42
|
-
* export const connectorConfigs: Record<string, ConnectorConfig> = { salesModel };
|
|
43
|
-
*/
|
|
44
|
-
export const connectorConfigs: Record<string, ConnectorConfig> = {};
|
|
45
|
-
|
|
46
|
-
/**
|
|
47
|
-
* Per-connector runtime hooks, keyed by the same name again.
|
|
48
|
-
*
|
|
49
|
-
* `fabric-semanticmodel` returns an Apache Arrow stream and chooses its
|
|
50
|
-
* transport from where the app is running — embedded in the Fabric portal, or
|
|
51
|
-
* standalone — and both of those live in the runtime. A connector left out of
|
|
52
|
-
* this map falls back to the plain JSON pass-through and will not decode.
|
|
53
|
-
* Register one runtime per semantic model; the connectors layer already keys
|
|
54
|
-
* instances by name.
|
|
55
|
-
*
|
|
56
|
-
* @example
|
|
57
|
-
* import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
|
|
58
|
-
*
|
|
59
|
-
* export const connectorRuntimes: ConnectorsRuntime = {
|
|
60
|
-
* salesModel: fabricSemanticModel({}),
|
|
61
|
-
* };
|
|
62
|
-
*
|
|
63
|
-
* @remarks
|
|
64
|
-
* Do not pass a `target`. The workspace and item ids come from `rayfin.yml` and
|
|
65
|
-
* are injected by the host, so they never ship to the browser. Deriving one from
|
|
66
|
-
* a `VITE_*` variable throws at module load, because a per-model URL is not
|
|
67
|
-
* among the variables `rayfin env` emits.
|
|
68
|
-
*/
|
|
69
|
-
export const connectorRuntimes: ConnectorsRuntime = {};
|
|
70
|
-
|
|
71
|
-
/**
|
|
72
|
-
* Fails when a connector is configured without a matching runtime.
|
|
73
|
-
*
|
|
74
|
-
* A config with no runtime still sends the call, falls back to JSON
|
|
75
|
-
* pass-through, and returns an Arrow stream nothing decodes — unreadable rows,
|
|
76
|
-
* far from the missing line that caused them. Call this before constructing the
|
|
77
|
-
* client to turn that into a startup error naming the connector.
|
|
78
|
-
*
|
|
79
|
-
* A runtime with no config is fine: it can be registered ahead of the
|
|
80
|
-
* `connector add` that declares it.
|
|
81
|
-
*/
|
|
82
|
-
export function assertConnectorRuntimesRegistered(): void {
|
|
83
|
-
const missing = Object.keys(connectorConfigs).filter(
|
|
84
|
-
(name) => !(name in connectorRuntimes)
|
|
85
|
-
);
|
|
86
|
-
|
|
87
|
-
if (missing.length > 0) {
|
|
88
|
-
throw new Error(
|
|
89
|
-
`Connector(s) ${missing.map((n) => `"${n}"`).join(', ')} are in connectorConfigs but have no runtime in connectorRuntimes ` +
|
|
90
|
-
`(packages/frontend/src/lib/connectors.ts). Without a runtime the response is not decoded and rows arrive unreadable. ` +
|
|
91
|
-
`Add: ${missing.map((n) => `${n}: fabricSemanticModel({})`).join(', ')}.`
|
|
92
|
-
);
|
|
93
|
-
}
|
|
94
|
-
}
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|