@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 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. Each folder under `skills/` is one agent skill
17
- and maps 1:1 to `.agents/skills/<name>/` in an app.
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` | Capability pack: `SKILL.md`, `pack.json`, and `kit/` (semantic-model query hook, connector wiring, schema scripts) |
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. The Rayfin universal template applies
28
- it with `npm run pack:add -- analytics`, and the copy targets assume that
29
- template's layout.
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`, `fabric-sdk`, and `app-validation`, which the app template
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('names an unregistered connector as a wiring mistake', async () => {
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).toContain('connectorRuntimes');
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}". Register it in connectorConfigs and ` +
59
- `connectorRuntimes (packages/frontend/src/lib/connectors.ts), and check the name matches ` +
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
- `packages/frontend/src/lib/rayfin-client.ts ` +
83
- `builds a plain RayfinClient; querying a semantic model needs ` +
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.0.0",
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: an existing file is preserved, not overwritten, so a
42
- `connectors.ts` you have registered models in survives.
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"` (row/byte cap
319
- — the rows are truncated), `"api"` (dataset-level or auth), or `"network"`.
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
- Prefer the field over `TOPN` when you want a guard rather than a deliberately
158
- ranked subset: exceeding it **fails** the query with an `overflow` error, so a
159
- bound that was too tight announces itself, where `TOPN` returns a
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
- }