Skip to content

Commit 3269d58

Browse files
committed
fix(docs): examples that compile, the right error import, no TypeScript strict mode, phone-width tables
Review findings on #42 (nik13): three emitted instructions failed for an installed-package consumer, and the reference tables widened phone pages. - Example values resolve `$ref` before choosing a shape: an object-valued field such as dashboards.query's `time_range` is shown as `{"preset": "30m"}` / `{ preset: "30m" }` (its required fields, or its first enum field), never as a placeholder string the compiler rejects. - The Errors overview imports from `fi.platform` and `@future-agi/sdk/platform`, with a note that the package root does not export the platform errors and its `RateLimitError` is an unrelated legacy class. - The model pages no longer promise `strictResponses: true`; strict mode is Python-only. - Every generated table sits in <div class="sdk-ref-table">, a bounded scroller styled by the docs site, so long identifiers scroll inside the table instead of widening the page. Installed-package checks, so this cannot regress silently: - python/consumer/docs_examples.py parses every Python example in the reference, resolves the `client.<...>` chain on a real fi.Client and binds the arguments to the method's signature; the documented imports are executed as written. Runs in the test suite and in CI's "Packages as installed" job against the wheel. - scripts/docs-examples.mjs turns every TypeScript example into a consumer module that check-consumer.sh compiles against the packed tarball (164 examples, plus the documented error import); check-consumer.sh also serves a real HTTP 429 and asserts it is caught as the platform RateLimitError.
1 parent 63307a0 commit 3269d58

40 files changed

Lines changed: 448 additions & 33 deletions

‎.github/workflows/ci.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,9 @@ jobs:
106106
# wheel installed into an empty virtualenv, the npm tarball installed into
107107
# an empty project. python/consumer/consumer.py and
108108
# typescript/futureagi/consumer/consumer-types.mts hold the public calls
109-
# that must run and type-check from there (mypy --strict, tsc --strict).
109+
# that must run and type-check from there (mypy --strict, tsc --strict),
110+
# and every example in the generated reference (docs/sdk-reference) must
111+
# bind (Python) and compile (TypeScript) against the installed package.
110112
runs-on: ubuntu-latest
111113
timeout-minutes: 15
112114
steps:

‎docs/sdk-reference/account-models.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@ title: "Account response models"
33
description: "The 8 response models returned by the account resources of the Future AGI Python and TypeScript SDKs, with every field and its type."
44
---
55

6-
The models returned by `client.account`, `client.workspaces`, `client.usage`, importable from `fi.platform.models` (Python) and `@future-agi/sdk/platform/models` (TypeScript). Types are language-neutral: `string[]` is a Python `list[str]` and a TypeScript `string[]`, and a type named after another model links to that model. Parsing is tolerant by default: a response that leaves a field out or adds one never breaks a call, and `strict_responses=True` (Python) or `strictResponses: true` (TypeScript) rejects a response that misses a field the contract requires (see the [overview](/docs/sdk/reference#strict-mode)).
6+
The models returned by `client.account`, `client.workspaces`, `client.usage`, importable from `fi.platform.models` (Python) and `@future-agi/sdk/platform/models` (TypeScript). Types are language-neutral: `string[]` is a Python `list[str]` and a TypeScript `string[]`, and a type named after another model links to that model. Parsing is tolerant by default: a response that leaves a field out or adds one never breaks a call. In Python, `Client(strict_responses=True)` rejects a response that misses a field the contract requires (see the [overview](/docs/sdk/reference#strict-mode)); TypeScript has no strict mode.
77

88
## Models
99

10+
<div class="sdk-ref-table">
11+
1012
| Model | Fields |
1113
|---|---|
1214
| <span id="usageoverviewdimension">`UsageOverviewDimension`</span> | `key: string`, `display_name: string`, `display_unit: string`, `current_usage: number`, `current_usage_raw: number`, `free_allowance: number`, `projected_usage: number`, `estimated_cost: number`, `tier_breakdown:` [`UsageTierBreakdown`](#usagetierbreakdown)[], `usage_pct: number` |
@@ -17,3 +19,5 @@ The models returned by `client.account`, `client.workspaces`, `client.usage`, im
1719
| <span id="userinfotwofactormethods">`UserInfoTwoFactorMethods`</span> | `totp: boolean`, `passkey: boolean` |
1820
| <span id="workspacemanagementitem">`WorkspaceManagementItem`</span> | `id: string`, `name: string`, `display_name: string`, `description: string`, `is_default: boolean`, `member_count: integer`, `created_at: string`, `created_by: string` |
1921
| <span id="workspacemanagementlistresult">`WorkspaceManagementListResult`</span> | `organization: string`, `workspaces:` [`WorkspaceManagementItem`](#workspacemanagementitem)[], `total: integer` |
22+
23+
</div>

‎docs/sdk-reference/account.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,14 @@ description: "Reference for client.account in the Future AGI Python and TypeScri
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`account.whoami`](#accountwhoami) | Return the authenticated user, organization, and workspace context. |
1315

16+
</div>
17+
1418
## client.account
1519

1620
### account.whoami

‎docs/sdk-reference/agents.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ description: "Reference for client.agents in the Future AGI Python and TypeScrip
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`agents.create`](#agentscreate) | Create a text or voice agent definition and its first active version. |
@@ -15,6 +17,8 @@ description: "Reference for client.agents in the Future AGI Python and TypeScrip
1517
| [`agents.update`](#agentsupdate) | Edit an agent definition. |
1618
| [`agents.versions.create`](#agentsversionscreate) | Snapshot agent configuration into a new version and activate it. |
1719

20+
</div>
21+
1822
## client.agents
1923

2024
### agents.create

‎docs/sdk-reference/alerts.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,15 @@ description: "Reference for client.alerts in the Future AGI Python and TypeScrip
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`alerts.logs.list`](#alertslogslist) | List alerts that have fired in numbered pages. |
1315
| [`alerts.rules.list`](#alertsruleslist) | List the configured alert monitors - what each one watches, its threshold and its project. |
1416

17+
</div>
18+
1519
## client.alerts
1620

1721
## client.alerts.logs

‎docs/sdk-reference/annotation-models.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@ title: "Annotation response models"
33
description: "The 30 response models returned by the annotation resources of the Future AGI Python and TypeScript SDKs, with every field and its type."
44
---
55

6-
The models returned by `client.annotation_queues`, `client.annotations`, `client.scores`, importable from `fi.platform.models` (Python) and `@future-agi/sdk/platform/models` (TypeScript). Types are language-neutral: `string[]` is a Python `list[str]` and a TypeScript `string[]`, and a type named after another model links to that model. Parsing is tolerant by default: a response that leaves a field out or adds one never breaks a call, and `strict_responses=True` (Python) or `strictResponses: true` (TypeScript) rejects a response that misses a field the contract requires (see the [overview](/docs/sdk/reference#strict-mode)).
6+
The models returned by `client.annotation_queues`, `client.annotations`, `client.scores`, importable from `fi.platform.models` (Python) and `@future-agi/sdk/platform/models` (TypeScript). Types are language-neutral: `string[]` is a Python `list[str]` and a TypeScript `string[]`, and a type named after another model links to that model. Parsing is tolerant by default: a response that leaves a field out or adds one never breaks a call. In Python, `Client(strict_responses=True)` rejects a response that misses a field the contract requires (see the [overview](/docs/sdk/reference#strict-mode)); TypeScript has no strict mode.
77

88
## Models
99

10+
<div class="sdk-ref-table">
11+
1012
| Model | Fields |
1113
|---|---|
1214
| <span id="annotationqueue">`AnnotationQueue`</span> | `id: string`, `name: string`, `description: string`, `instructions: string`, `status: string`, `assignment_strategy: string`, `annotations_required: integer`, `reservation_timeout_minutes: integer`, `requires_review: boolean`, `auto_assign: boolean`, `organization: string`, `project: string`, `dataset: string`, `agent_definition: string`, `is_default: boolean`, `labels:` [`QueueLabelNested`](#queuelabelnested)[], `annotators:` [`QueueAnnotatorNested`](#queueannotatornested)[], `label_ids: string[]`, `annotator_ids: string[]`, `annotator_roles: any`, `label_count: integer`, `annotator_count: integer`, `item_count: integer`, `completed_count: integer`, `created_by: string`, `created_by_name: string`, `viewer_role: string`, `viewer_roles: string[]`, `deleted: boolean`, `created_at: string` |
@@ -39,3 +41,5 @@ The models returned by `client.annotation_queues`, `client.annotations`, `client
3941
| <span id="queueremovelabelresult">`QueueRemoveLabelResult`</span> | `removed: boolean` |
4042
| <span id="queuesubmitannotationsresult">`QueueSubmitAnnotationsResult`</span> | `submitted: integer` |
4143
| <span id="score">`Score`</span> | `id: string`, `source_type: string`, `source_id: any`, `label_id: string`, `label_name: string`, `label_type: string`, `label_settings: any`, `label_allow_notes: boolean`, `value: any`, `value_history: any`, `score_source: string`, `notes: string`, `annotator: string`, `annotator_name: string`, `annotator_email: string`, `queue_item: string`, `queue_id: any`, `created_at: string`, `updated_at: string` |
44+
45+
</div>

‎docs/sdk-reference/annotation-queues.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ description: "Reference for client.annotation_queues in the Future AGI Python an
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`annotation_queues.add_label`](#annotation_queuesadd_label) | Add an annotation label to a queue. |
@@ -33,6 +35,8 @@ description: "Reference for client.annotation_queues in the Future AGI Python an
3335
| [`annotation_queues.items.skip`](#annotation_queuesitemsskip) | Skip a queue item and return the next one to work on. |
3436
| [`annotation_queues.items.submit`](#annotation_queuesitemssubmit) | Submit annotation values for an item in an annotation queue. |
3537

38+
</div>
39+
3640
## client.annotation_queues
3741

3842
### annotation_queues.add_label

‎docs/sdk-reference/annotations.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ description: "Reference for client.annotations in the Future AGI Python and Type
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`annotations.bulk_create`](#annotationsbulk_create) | Create or update annotations and notes on spans in bulk. |
@@ -15,6 +17,8 @@ description: "Reference for client.annotations in the Future AGI Python and Type
1517
| [`annotations.labels.get`](#annotationslabelsget) | Return an annotation label by id. |
1618
| [`annotations.labels.list`](#annotationslabelslist) | List annotation labels, optionally filtered by project, type or search text. |
1719

20+
</div>
21+
1822
## client.annotations
1923

2024
### annotations.bulk_create

‎docs/sdk-reference/dashboards.mdx‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ description: "Reference for client.dashboards in the Future AGI Python and TypeS
77

88
## Methods
99

10+
<div class="sdk-ref-table">
11+
1012
| Method | Description |
1113
|---|---|
1214
| [`dashboards.create`](#dashboardscreate) | Create an empty dashboard in the current workspace; add widgets with create_dashboard_widget. |
@@ -23,6 +25,8 @@ description: "Reference for client.dashboards in the Future AGI Python and TypeS
2325
| [`dashboards.widgets.query`](#dashboardswidgetsquery) | Execute a saved widget's query and return its chart data. |
2426
| [`dashboards.widgets.update`](#dashboardswidgetsupdate) | Update selected fields on a dashboard widget, such as its query_config, chart_config, or layout. |
2527

28+
</div>
29+
2630
## client.dashboards
2731

2832
### dashboards.create
@@ -307,12 +311,12 @@ Run an ad-hoc dashboard query (time_range and metrics, with optional filters and
307311
<CodeGroup>
308312

309313
```python Python
310-
result = client.dashboards.query(time_range="your-time-range", metrics=[])
314+
result = client.dashboards.query(time_range={"preset": "30m"}, metrics=[])
311315
```
312316

313317
```typescript TypeScript
314318
const result = await client.dashboards.query({
315-
time_range: "your-time-range",
319+
time_range: { preset: "30m" },
316320
metrics: [],
317321
});
318322
```

‎docs/sdk-reference/datasets-evals-models.mdx‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@ title: "Datasets & evals response models"
33
description: "The 42 response models returned by the datasets & evals resources of the Future AGI Python and TypeScript SDKs, with every field and its type."
44
---
55

6-
The models returned by `client.datasets`, `client.evals`, `client.experiments`, `client.optimizations`, importable from `fi.platform.models` (Python) and `@future-agi/sdk/platform/models` (TypeScript). Types are language-neutral: `string[]` is a Python `list[str]` and a TypeScript `string[]`, and a type named after another model links to that model. Parsing is tolerant by default: a response that leaves a field out or adds one never breaks a call, and `strict_responses=True` (Python) or `strictResponses: true` (TypeScript) rejects a response that misses a field the contract requires (see the [overview](/docs/sdk/reference#strict-mode)).
6+
The models returned by `client.datasets`, `client.evals`, `client.experiments`, `client.optimizations`, importable from `fi.platform.models` (Python) and `@future-agi/sdk/platform/models` (TypeScript). Types are language-neutral: `string[]` is a Python `list[str]` and a TypeScript `string[]`, and a type named after another model links to that model. Parsing is tolerant by default: a response that leaves a field out or adds one never breaks a call. In Python, `Client(strict_responses=True)` rejects a response that misses a field the contract requires (see the [overview](/docs/sdk/reference#strict-mode)); TypeScript has no strict mode.
77

88
## Models
99

10+
<div class="sdk-ref-table">
11+
1012
| Model | Fields |
1113
|---|---|
1214
| <span id="column">`Column`</span> | `id: string`, `name: string`, `data_type: string`, `dataset: string`, `source: string`, `source_id: string` |
@@ -51,3 +53,5 @@ The models returned by `client.datasets`, `client.evals`, `client.experiments`,
5153
| <span id="optimizationscreateresult">`OptimizationsCreateResult`</span> | `id: string`, `name: string`, `optimizer_algorithm: string`, `optimizer_config: any`, `created_at: string` |
5254
| <span id="_evaltasklistresultresponse">`_EvalTaskListResultResponse`</span> | `metadata: any`, `table:` [`_EvalTaskListRowResponse`](#_evaltasklistrowresponse)[], `config: any[]` |
5355
| <span id="_evaltasklistrowresponse">`_EvalTaskListRowResponse`</span> | `id: string`, `name: string`, `project_name: string`, `status: string`, `run_type: string`, `filters_applied: any`, `created_at: string`, `evals_applied: string[]`, `sampling_rate: number`, `last_run: string` |
56+
57+
</div>

0 commit comments

Comments
 (0)