From ab903e0191de071a417a08eb4ad939ab7916e0a7 Mon Sep 17 00:00:00 2001 From: tanmaycode1 Date: Wed, 4 Nov 2026 13:08:27 +0530 Subject: [PATCH 1/7] docs(sdk): add the generated platform SDK reference and its sync Add the Platform SDK Reference group to the SDK tab: 34 pages generated by future-agi/futureagi-sdk from its API contract (an overview, one page per resource with examples, signatures, parameters and returns, and a models table per area). The pages are never edited here. scripts/sync-sdk-reference.mjs copies the pages and the sidebar group from an SDK checkout and checks nav/page parity; .github/workflows/sdk-reference-sync.yml runs it weekly, on an SDK release dispatch or by hand, and opens a PR against main. audit-links.mjs now audits the generated group too. The ParamField styles move to a shared stylesheet so ResponseField renders styled on its own. --- .github/workflows/sdk-reference-sync.yml | 77 + scripts/audit-links.mjs | 2 + scripts/sync-sdk-reference.mjs | 85 + src/components/docs/ParamField.astro | 97 +- src/components/docs/ResponseField.astro | 2 + src/lib/navigation.ts | 3 + src/lib/sdk-reference.mjs | 190 +++ .../docs/sdk/reference/account-models.mdx | 19 + src/pages/docs/sdk/reference/account.mdx | 58 + src/pages/docs/sdk/reference/agents.mdx | 508 ++++++ src/pages/docs/sdk/reference/alerts.mdx | 153 ++ .../docs/sdk/reference/annotation-models.mdx | 41 + .../docs/sdk/reference/annotation-queues.mdx | 1405 +++++++++++++++++ src/pages/docs/sdk/reference/annotations.mdx | 305 ++++ src/pages/docs/sdk/reference/dashboards.mdx | 845 ++++++++++ .../sdk/reference/datasets-evals-models.mdx | 53 + src/pages/docs/sdk/reference/datasets.mdx | 1279 +++++++++++++++ .../docs/sdk/reference/error-clusters.mdx | 150 ++ src/pages/docs/sdk/reference/evals.mdx | 1159 ++++++++++++++ src/pages/docs/sdk/reference/experiments.mdx | 216 +++ .../sdk/reference/file-knowledge-bases.mdx | 385 +++++ .../docs/sdk/reference/gateway-models.mdx | 19 + src/pages/docs/sdk/reference/gateway.mdx | 487 ++++++ src/pages/docs/sdk/reference/index.mdx | 260 +++ .../sdk/reference/knowledge-bases-models.mdx | 21 + .../docs/sdk/reference/knowledge-bases.mdx | 289 ++++ src/pages/docs/sdk/reference/models.mdx | 56 + .../sdk/reference/observability-models.mdx | 57 + .../docs/sdk/reference/optimizations.mdx | 199 +++ src/pages/docs/sdk/reference/projects.mdx | 132 ++ .../docs/sdk/reference/prompts-models.mdx | 17 + src/pages/docs/sdk/reference/prompts.mdx | 1388 ++++++++++++++++ .../docs/sdk/reference/provider-keys.mdx | 71 + src/pages/docs/sdk/reference/scores.mdx | 240 +++ src/pages/docs/sdk/reference/sessions.mdx | 171 ++ .../docs/sdk/reference/simulation-models.mdx | 31 + src/pages/docs/sdk/reference/simulation.mdx | 781 +++++++++ src/pages/docs/sdk/reference/spans.mdx | 177 +++ src/pages/docs/sdk/reference/traces.mdx | 312 ++++ src/pages/docs/sdk/reference/usage.mdx | 69 + src/pages/docs/sdk/reference/workspaces.mdx | 106 ++ src/styles/fapi-param.css | 94 ++ 42 files changed, 11914 insertions(+), 95 deletions(-) create mode 100644 .github/workflows/sdk-reference-sync.yml create mode 100644 scripts/sync-sdk-reference.mjs create mode 100644 src/lib/sdk-reference.mjs create mode 100644 src/pages/docs/sdk/reference/account-models.mdx create mode 100644 src/pages/docs/sdk/reference/account.mdx create mode 100644 src/pages/docs/sdk/reference/agents.mdx create mode 100644 src/pages/docs/sdk/reference/alerts.mdx create mode 100644 src/pages/docs/sdk/reference/annotation-models.mdx create mode 100644 src/pages/docs/sdk/reference/annotation-queues.mdx create mode 100644 src/pages/docs/sdk/reference/annotations.mdx create mode 100644 src/pages/docs/sdk/reference/dashboards.mdx create mode 100644 src/pages/docs/sdk/reference/datasets-evals-models.mdx create mode 100644 src/pages/docs/sdk/reference/datasets.mdx create mode 100644 src/pages/docs/sdk/reference/error-clusters.mdx create mode 100644 src/pages/docs/sdk/reference/evals.mdx create mode 100644 src/pages/docs/sdk/reference/experiments.mdx create mode 100644 src/pages/docs/sdk/reference/file-knowledge-bases.mdx create mode 100644 src/pages/docs/sdk/reference/gateway-models.mdx create mode 100644 src/pages/docs/sdk/reference/gateway.mdx create mode 100644 src/pages/docs/sdk/reference/index.mdx create mode 100644 src/pages/docs/sdk/reference/knowledge-bases-models.mdx create mode 100644 src/pages/docs/sdk/reference/knowledge-bases.mdx create mode 100644 src/pages/docs/sdk/reference/models.mdx create mode 100644 src/pages/docs/sdk/reference/observability-models.mdx create mode 100644 src/pages/docs/sdk/reference/optimizations.mdx create mode 100644 src/pages/docs/sdk/reference/projects.mdx create mode 100644 src/pages/docs/sdk/reference/prompts-models.mdx create mode 100644 src/pages/docs/sdk/reference/prompts.mdx create mode 100644 src/pages/docs/sdk/reference/provider-keys.mdx create mode 100644 src/pages/docs/sdk/reference/scores.mdx create mode 100644 src/pages/docs/sdk/reference/sessions.mdx create mode 100644 src/pages/docs/sdk/reference/simulation-models.mdx create mode 100644 src/pages/docs/sdk/reference/simulation.mdx create mode 100644 src/pages/docs/sdk/reference/spans.mdx create mode 100644 src/pages/docs/sdk/reference/traces.mdx create mode 100644 src/pages/docs/sdk/reference/usage.mdx create mode 100644 src/pages/docs/sdk/reference/workspaces.mdx create mode 100644 src/styles/fapi-param.css diff --git a/.github/workflows/sdk-reference-sync.yml b/.github/workflows/sdk-reference-sync.yml new file mode 100644 index 000000000..5d549d9d0 --- /dev/null +++ b/.github/workflows/sdk-reference-sync.yml @@ -0,0 +1,77 @@ +# Refreshes the platform SDK reference (src/pages/docs/sdk/reference) from the SDK +# repository's generated pages and opens a PR against main. Run it by hand for a given SDK +# ref, let the SDK repository dispatch it on a release, or rely on the weekly run. +name: sdk-reference-sync + +on: + workflow_dispatch: + inputs: + sdk_ref: + description: futureagi-sdk ref to sync from (branch, tag or SHA) + default: dev + repository_dispatch: + types: [sdk-release] # client_payload.ref: the SDK ref to sync from + schedule: + - cron: '0 6 * * 1' # Mondays 06:00 UTC, from the SDK's dev branch + +permissions: + contents: write + pull-requests: write + +jobs: + sync: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + # App token (not GITHUB_TOKEN): the org forbids Actions from creating PRs + # with GITHUB_TOKEN, and App-minted tokens are exempt. Scoped to this repo. + - uses: actions/create-github-app-token@v2 + id: app-token + with: + app-id: ${{ secrets.RELEASE_BOT_APP_ID }} + private-key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }} + - uses: actions/checkout@v4 + with: + ref: main + token: ${{ steps.app-token.outputs.token }} + - name: Resolve the SDK ref + id: ref + env: + INPUT_REF: ${{ inputs.sdk_ref }} + DISPATCH_REF: ${{ github.event.client_payload.ref }} + run: echo "ref=${INPUT_REF:-${DISPATCH_REF:-dev}}" >> "$GITHUB_OUTPUT" + - name: Check out the generated reference from the SDK repository + uses: actions/checkout@v4 + with: + repository: future-agi/futureagi-sdk + ref: ${{ steps.ref.outputs.ref }} + path: .sdk + sparse-checkout: docs/sdk-reference + persist-credentials: false + - uses: actions/setup-node@v4 + with: + node-version: 20 + - name: Sync the pages and the sidebar group + run: node scripts/sync-sdk-reference.mjs --from .sdk + - name: Check nav and content links + run: node scripts/audit-links.mjs + - name: Open PR + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + SDK_REF: ${{ steps.ref.outputs.ref }} + run: | + set -eu + if git diff --quiet -- src/pages/docs/sdk/reference src/lib/sdk-reference.mjs; then + echo "reference already current"; exit 0 + fi + sha=$(git -C .sdk rev-parse --short HEAD) + branch="chore/sdk-reference-${sha}" + git config user.name "futureagi-release-bot" + git config user.email "release-bot@futureagi.com" + git switch -c "$branch" + git add src/pages/docs/sdk/reference src/lib/sdk-reference.mjs + git commit -m "docs(sdk): sync the platform SDK reference from futureagi-sdk@${sha}" + git push origin "$branch" + gh pr create --base main --head "$branch" \ + --title "docs(sdk): platform SDK reference from futureagi-sdk@${sha}" \ + --body "Generated pages from [future-agi/futureagi-sdk@${sha}](https://github.com/future-agi/futureagi-sdk/tree/${sha}/docs/sdk-reference) (ref \`${SDK_REF}\`), copied by \`scripts/sync-sdk-reference.mjs\`. Do not edit the pages here: fix the generator in the SDK repository and re-run the sync." diff --git a/scripts/audit-links.mjs b/scripts/audit-links.mjs index 88c51172c..cf8676c13 100644 --- a/scripts/audit-links.mjs +++ b/scripts/audit-links.mjs @@ -15,6 +15,7 @@ import fs from 'fs'; import path from 'path'; import { fileURLToPath } from 'url'; import { integrationNavigation } from '../src/lib/integrations.mjs'; +import { sdkReferenceNavigation } from '../src/lib/sdk-reference.mjs'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); const ROOT = path.resolve(__dirname, '..'); @@ -67,6 +68,7 @@ function addCatalogLinks(items) { } } addCatalogLinks(integrationNavigation); +addCatalogLinks(sdkReferenceNavigation.items); // ── 3. Extract all internal links from MDX files ────────────── function findMdxFiles(dir) { diff --git a/scripts/sync-sdk-reference.mjs b/scripts/sync-sdk-reference.mjs new file mode 100644 index 000000000..ad7239407 --- /dev/null +++ b/scripts/sync-sdk-reference.mjs @@ -0,0 +1,85 @@ +// @ts-check +/** + * Copy the generated platform SDK reference out of a futureagi-sdk checkout. + * + * node scripts/sync-sdk-reference.mjs --from ../futureagi-sdk + * + * The SDK repository generates `docs/sdk-reference/` (one MDX page per resource, an + * overview, and `navigation.json`) from its API contract with `python sdkgen/generate.py`. + * This script replaces `src/pages/docs/sdk/reference/` with those pages and rewrites + * `src/lib/sdk-reference.mjs`, the sidebar group `navigation.ts` imports. Never edit the + * copied pages by hand: fix the generator in the SDK repository and sync again. + * `.github/workflows/sdk-reference-sync.yml` runs this and opens a PR. + */ +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); +const PAGES_DIR = path.join(ROOT, 'src/pages/docs/sdk/reference'); +const NAV_FILE = path.join(ROOT, 'src/lib/sdk-reference.mjs'); + +const args = process.argv.slice(2); +const fromIndex = args.indexOf('--from'); +if (fromIndex === -1 || !args[fromIndex + 1]) { + console.error('usage: node scripts/sync-sdk-reference.mjs --from '); + process.exit(2); +} +const source = path.resolve(args[fromIndex + 1], 'docs/sdk-reference'); +const navSource = path.join(source, 'navigation.json'); +if (!fs.existsSync(path.join(source, 'index.mdx')) || !fs.existsSync(navSource)) { + console.error(`${source} does not hold a generated reference (index.mdx + navigation.json); run python sdkgen/generate.py in the SDK checkout first`); + process.exit(1); +} + +/** @type {{group: string, icon?: string, items: {title: string, href?: string, items?: {title: string, href: string}[]}[]}} */ +const nav = JSON.parse(fs.readFileSync(navSource, 'utf-8')); +const pages = fs.readdirSync(source).filter((name) => name.endsWith('.mdx')).sort(); + +// Every nav item must have a page and every page a nav item, or the sidebar and the site drift. +/** @param {{href?: string, items?: any[]}[]} items */ +function* walk(items) { + for (const item of items) { + if (item.href) yield item.href; + if (item.items) yield* walk(item.items); + } +} +const hrefs = new Set(walk(nav.items)); +for (const page of pages) { + const href = page === 'index.mdx' ? '/docs/sdk/reference' : `/docs/sdk/reference/${page.replace(/\.mdx$/, '')}`; + if (!hrefs.has(href)) { + console.error(`${page} is not in navigation.json`); + process.exit(1); + } + hrefs.delete(href); +} +if (hrefs.size) { + console.error(`navigation.json lists pages that do not exist: ${[...hrefs].join(', ')}`); + process.exit(1); +} + +fs.mkdirSync(PAGES_DIR, { recursive: true }); +let removed = 0; +for (const name of fs.readdirSync(PAGES_DIR)) { + if (name.endsWith('.mdx') && !pages.includes(name)) { + fs.unlinkSync(path.join(PAGES_DIR, name)); + removed++; + } +} +for (const page of pages) { + fs.copyFileSync(path.join(source, page), path.join(PAGES_DIR, page)); +} + +const navModule = `// @ts-check +/** + * Sidebar group for the platform SDK reference. Generated by + * scripts/sync-sdk-reference.mjs from the SDK repository's docs/sdk-reference/navigation.json; + * do not edit. navigation.ts places it in the SDK tab and scripts/audit-links.mjs audits it. + * + * @type {{group: string, icon?: string, items: ReadonlyArray<{title: string, href?: string, items?: ReadonlyArray<{title: string, href: string}>}>}} + */ +export const sdkReferenceNavigation = ${JSON.stringify(nav, null, 2)}; +`; +fs.writeFileSync(NAV_FILE, navModule); + +console.log(`sdk reference: ${pages.length} pages copied, ${removed} stale removed, ${[...walk(nav.items)].length} nav links`); diff --git a/src/components/docs/ParamField.astro b/src/components/docs/ParamField.astro index de100ff3f..c42100bf4 100644 --- a/src/components/docs/ParamField.astro +++ b/src/components/docs/ParamField.astro @@ -11,6 +11,8 @@ * The name of the evaluation group. * */ +import '../../styles/fapi-param.css'; + interface Props { path?: string; query?: string; @@ -61,98 +63,3 @@ const paramKind = path ? 'path' : query ? 'query' : body ? 'body' : header ? 'he )} - diff --git a/src/components/docs/ResponseField.astro b/src/components/docs/ResponseField.astro index ef6ea9da0..f5e05f1b1 100644 --- a/src/components/docs/ResponseField.astro +++ b/src/components/docs/ResponseField.astro @@ -7,6 +7,8 @@ * Unique identifier for the resource. * */ +import '../../styles/fapi-param.css'; + interface Props { name: string; type?: string; diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index a8101e941..b7ed23423 100644 --- a/src/lib/navigation.ts +++ b/src/lib/navigation.ts @@ -7,6 +7,7 @@ */ import { integrationNavigation } from './integrations.mjs'; +import { sdkReferenceNavigation } from './sdk-reference.mjs'; export interface NavItem { title: string; @@ -1148,6 +1149,8 @@ export const tabNavigation: NavTab[] = [ }, ] }, + // Generated from the SDK repository (scripts/sync-sdk-reference.mjs); one page per resource. + sdkReferenceNavigation, { group: 'Evaluation', icon: 'chart', diff --git a/src/lib/sdk-reference.mjs b/src/lib/sdk-reference.mjs new file mode 100644 index 000000000..d4e6c7429 --- /dev/null +++ b/src/lib/sdk-reference.mjs @@ -0,0 +1,190 @@ +// @ts-check +/** + * Sidebar group for the platform SDK reference. Generated by + * scripts/sync-sdk-reference.mjs from the SDK repository's docs/sdk-reference/navigation.json; + * do not edit. navigation.ts places it in the SDK tab and scripts/audit-links.mjs audits it. + * + * @type {{group: string, icon?: string, items: ReadonlyArray<{title: string, href?: string, items?: ReadonlyArray<{title: string, href: string}>}>}} + */ +export const sdkReferenceNavigation = { + "group": "Platform SDK Reference", + "icon": "code", + "items": [ + { + "title": "Overview", + "href": "/docs/sdk/reference" + }, + { + "title": "Account", + "items": [ + { + "title": "Account", + "href": "/docs/sdk/reference/account" + }, + { + "title": "Workspaces", + "href": "/docs/sdk/reference/workspaces" + }, + { + "title": "Usage", + "href": "/docs/sdk/reference/usage" + }, + { + "title": "Response models", + "href": "/docs/sdk/reference/account-models" + } + ] + }, + { + "title": "Datasets & evals", + "items": [ + { + "title": "Datasets", + "href": "/docs/sdk/reference/datasets" + }, + { + "title": "Evals", + "href": "/docs/sdk/reference/evals" + }, + { + "title": "Experiments", + "href": "/docs/sdk/reference/experiments" + }, + { + "title": "Optimizations", + "href": "/docs/sdk/reference/optimizations" + }, + { + "title": "Response models", + "href": "/docs/sdk/reference/datasets-evals-models" + } + ] + }, + { + "title": "Prompts", + "items": [ + { + "title": "Prompts", + "href": "/docs/sdk/reference/prompts" + }, + { + "title": "Response models", + "href": "/docs/sdk/reference/prompts-models" + } + ] + }, + { + "title": "Observability", + "items": [ + { + "title": "Projects", + "href": "/docs/sdk/reference/projects" + }, + { + "title": "Traces", + "href": "/docs/sdk/reference/traces" + }, + { + "title": "Spans", + "href": "/docs/sdk/reference/spans" + }, + { + "title": "Sessions", + "href": "/docs/sdk/reference/sessions" + }, + { + "title": "Dashboards", + "href": "/docs/sdk/reference/dashboards" + }, + { + "title": "Error clusters", + "href": "/docs/sdk/reference/error-clusters" + }, + { + "title": "Alerts", + "href": "/docs/sdk/reference/alerts" + }, + { + "title": "Response models", + "href": "/docs/sdk/reference/observability-models" + } + ] + }, + { + "title": "Annotation", + "items": [ + { + "title": "Annotation queues", + "href": "/docs/sdk/reference/annotation-queues" + }, + { + "title": "Annotations", + "href": "/docs/sdk/reference/annotations" + }, + { + "title": "Scores", + "href": "/docs/sdk/reference/scores" + }, + { + "title": "Response models", + "href": "/docs/sdk/reference/annotation-models" + } + ] + }, + { + "title": "Simulation", + "items": [ + { + "title": "Agents", + "href": "/docs/sdk/reference/agents" + }, + { + "title": "Simulation", + "href": "/docs/sdk/reference/simulation" + }, + { + "title": "Response models", + "href": "/docs/sdk/reference/simulation-models" + } + ] + }, + { + "title": "Knowledge bases", + "items": [ + { + "title": "Knowledge bases", + "href": "/docs/sdk/reference/knowledge-bases" + }, + { + "title": "File knowledge bases", + "href": "/docs/sdk/reference/file-knowledge-bases" + }, + { + "title": "Response models", + "href": "/docs/sdk/reference/knowledge-bases-models" + } + ] + }, + { + "title": "Gateway", + "items": [ + { + "title": "Gateway", + "href": "/docs/sdk/reference/gateway" + }, + { + "title": "Models", + "href": "/docs/sdk/reference/models" + }, + { + "title": "Provider keys", + "href": "/docs/sdk/reference/provider-keys" + }, + { + "title": "Response models", + "href": "/docs/sdk/reference/gateway-models" + } + ] + } + ] +}; diff --git a/src/pages/docs/sdk/reference/account-models.mdx b/src/pages/docs/sdk/reference/account-models.mdx new file mode 100644 index 000000000..d1f7c0147 --- /dev/null +++ b/src/pages/docs/sdk/reference/account-models.mdx @@ -0,0 +1,19 @@ +--- +title: "Account response models" +description: "The 8 response models returned by the account resources of the Future AGI Python and TypeScript SDKs, with every field and its type." +--- + +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)). + +## Models + +| Model | Fields | +|---|---| +| `UsageOverviewDimension` | `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` | +| `UsageOverviewResult` | `plan: string`, `plan_display_name: string`, `platform_fee: number`, `period: string`, `billing_period_start: string`, `billing_period_end: string`, `total_estimated_cost: number`, `total_with_platform: number`, `dimensions:` [`UsageOverviewDimension`](#usageoverviewdimension)[], `pending_cancel: boolean`, `cancel_at: string` | +| `UsageTierBreakdown` | `tier_start: number`, `tier_end: number`, `quantity: number`, `rate: number`, `cost: number` | +| `UserInfoOrganization` | `id: string`, `name: string`, `display_name: string`, `ws_enabled: boolean` | +| `UserInfoResponse` | `id: string`, `email: string`, `name: string`, `organization_role: string`, `organization:` [`UserInfoOrganization`](#userinfoorganization), `created_at: string`, `status: string`, `role: string`, `goals: string[]`, `remember_me: boolean`, `get_started_completed: boolean`, `onboarding_completed: boolean`, `ws_enabled: boolean`, `requires_org_setup: boolean`, `default_workspace_id: string`, `default_workspace_name: string`, `default_workspace_display_name: string`, `default_workspace_role: string`, `org_level: integer`, `ws_level: integer`, `effective_level: integer`, `has_2fa_enabled: boolean`, `two_factor_methods:` [`UserInfoTwoFactorMethods`](#userinfotwofactormethods), `org_2fa_required: boolean`, `org_2fa_grace_ends_at: string` | +| `UserInfoTwoFactorMethods` | `totp: boolean`, `passkey: boolean` | +| `WorkspaceManagementItem` | `id: string`, `name: string`, `display_name: string`, `description: string`, `is_default: boolean`, `member_count: integer`, `created_at: string`, `created_by: string` | +| `WorkspaceManagementListResult` | `organization: string`, `workspaces:` [`WorkspaceManagementItem`](#workspacemanagementitem)[], `total: integer` | diff --git a/src/pages/docs/sdk/reference/account.mdx b/src/pages/docs/sdk/reference/account.mdx new file mode 100644 index 000000000..be4b0b198 --- /dev/null +++ b/src/pages/docs/sdk/reference/account.mdx @@ -0,0 +1,58 @@ +--- +title: "Account" +description: "Reference for client.account in the Future AGI Python and TypeScript SDKs: account.whoami." +--- + +`client.account` on `fi.Client` (Python) and `client.account` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Account response models](/docs/sdk/reference/account-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`account.whoami`](#accountwhoami) | Return the authenticated user, organization, and workspace context. | + +## client.account + +### account.whoami + +Return the authenticated user, organization, and workspace context. + + + +**MCP tool**: `whoami` + + + +```python Python +result = client.account.whoami() +``` + +```typescript TypeScript +const result = await client.account.whoami(); +``` + + + + + +```python Python +client.account.whoami( + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.UserInfoResponse +``` + +```typescript TypeScript +client.account.whoami(options?: RequestOptions): Promise +``` + + + +#### Parameters + +This method takes no parameters beyond the per-call `options`. + +#### Returns + +[`UserInfoResponse`](/docs/sdk/reference/account-models#userinforesponse). diff --git a/src/pages/docs/sdk/reference/agents.mdx b/src/pages/docs/sdk/reference/agents.mdx new file mode 100644 index 000000000..caddaf5a2 --- /dev/null +++ b/src/pages/docs/sdk/reference/agents.mdx @@ -0,0 +1,508 @@ +--- +title: "Agents" +description: "Reference for client.agents in the Future AGI Python and TypeScript SDKs: agents.create, agents.get, agents.list, agents.update, agents.versions.create." +--- + +`client.agents` on `fi.Client` (Python) and `client.agents` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.agents.versions`. The models these methods return are on [Simulation response models](/docs/sdk/reference/simulation-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`agents.create`](#agentscreate) | Create a text or voice agent definition and its first active version. | +| [`agents.get`](#agentsget) | Return an agent definition by its identifier. | +| [`agents.list`](#agentslist) | List agent definitions in the current workspace. | +| [`agents.update`](#agentsupdate) | Edit an agent definition. | +| [`agents.versions.create`](#agentsversionscreate) | Snapshot agent configuration into a new version and activate it. | + +## client.agents + +### agents.create + +Create a text or voice agent definition and its first active version. Supply agent_name, agent_type and commit_message plus the configuration required for the chosen provider. + + + +**MCP tool**: `create_agent` + + + +```python Python +result = client.agents.create( + agent_name="your-agent-name", + agent_type="voice", + commit_message="your-commit-message", +) +``` + +```typescript TypeScript +const result = await client.agents.create({ + agent_name: "your-agent-name", + agent_type: "voice", + commit_message: "your-commit-message", +}); +``` + + + + + +```python Python +client.agents.create( + *, + agent_name: str, + agent_type: Literal['voice', 'text'], + commit_message: str, + inbound: bool | None | NotGiven = NOT_GIVEN, + target_speaks_first: bool | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + provider: str | None | NotGiven = NOT_GIVEN, + api_key: str | None | NotGiven = NOT_GIVEN, + assistant_id: str | None | NotGiven = NOT_GIVEN, + authentication_method: Literal['api_key'] | None | NotGiven = NOT_GIVEN, + language: str | None | NotGiven = NOT_GIVEN, + languages: list[str] | None | NotGiven = NOT_GIVEN, + contact_number: str | None | NotGiven = NOT_GIVEN, + knowledge_base: str | None | NotGiven = NOT_GIVEN, + observability_enabled: bool | None | NotGiven = NOT_GIVEN, + model: str | None | NotGiven = NOT_GIVEN, + model_details: dict[str, Any] | None | NotGiven = NOT_GIVEN, + websocket_url: str | None | NotGiven = NOT_GIVEN, + websocket_headers: dict[str, Any] | None | NotGiven = NOT_GIVEN, + replay_session_id: str | None | NotGiven = NOT_GIVEN, + livekit_url: str | None | NotGiven = NOT_GIVEN, + livekit_api_key: str | None | NotGiven = NOT_GIVEN, + livekit_api_secret: str | None | NotGiven = NOT_GIVEN, + livekit_agent_name: str | None | NotGiven = NOT_GIVEN, + livekit_config_json: dict[str, Any] | None | NotGiven = NOT_GIVEN, + livekit_max_concurrency: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.AgentDefinitionCreateResponse +``` + +```typescript TypeScript +client.agents.create(params: AgentsCreateParams, options?: RequestOptions): Promise + +export interface AgentsCreateParams { + agent_name: string; + agent_type: "voice" | "text"; + commit_message: string; + inbound?: boolean | null; + target_speaks_first?: boolean | null; + description?: string | null; + provider?: string | null; + api_key?: string | null; + assistant_id?: string | null; + authentication_method?: "api_key" | null; + language?: string | null; + languages?: Array | null; + contact_number?: string | null; + knowledge_base?: string | null; + observability_enabled?: boolean | null; + model?: string | null; + model_details?: Record | null; + websocket_url?: string | null; + websocket_headers?: Record | null; + replay_session_id?: string | null; + livekit_url?: string | null; + livekit_api_key?: string | null; + livekit_api_secret?: string | null; + livekit_agent_name?: string | null; + livekit_config_json?: Record | null; + livekit_max_concurrency?: number | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + +#### Returns + +[`AgentDefinitionCreateResponse`](/docs/sdk/reference/simulation-models#agentdefinitioncreateresponse). + +### agents.get + +Return an agent definition by its identifier. + + + +**MCP tool**: `get_agent` + + + +```python Python +result = client.agents.get("your-agent-id") +``` + +```typescript TypeScript +const result = await client.agents.get("your-agent-id"); +``` + + + + + +```python Python +client.agents.get( + agent_id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.AgentDefinitionDetailResponse +``` + +```typescript TypeScript +client.agents.get(agentId: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `agent_id`. + + +#### Returns + +[`AgentDefinitionDetailResponse`](/docs/sdk/reference/simulation-models#agentdefinitiondetailresponse). + +### agents.list + +List agent definitions in the current workspace. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_agents` + + + +```python Python +for item in client.agents.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.agents.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.agents.list( + *, + search: str | None | NotGiven = NOT_GIVEN, + agent_type: Literal['voice', 'text'] | None | NotGiven = NOT_GIVEN, + agent_definition_id: str | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.AgentDefinitionListResponse] +``` + +```typescript TypeScript +client.agents.list(params: AgentsListParams = {}, options?: RequestOptions): Pager + +export interface AgentsListParams { + search?: string | null; + agent_type?: "voice" | "text" | null; + agent_definition_id?: string | null; + limit?: number | null; +} +``` + + + +#### Parameters + + + + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`AgentDefinitionListResponse`](/docs/sdk/reference/simulation-models#agentdefinitionlistresponse) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### agents.update + +Edit an agent definition. Leave observability_enabled out to keep observability as it is; send true or false to turn it on or off. To use changed configuration in a versioned simulation, subsequently call create_agent_version, or supply the changes directly to create_agent_version. + + + +**MCP tool**: `update_agent` + + + +```python Python +result = client.agents.update("your-agent-id") +``` + +```typescript TypeScript +const result = await client.agents.update("your-agent-id"); +``` + + + + + +```python Python +client.agents.update( + agent_id: str, + *, + observability_enabled: bool | None | NotGiven = NOT_GIVEN, + agent_name: str | None | NotGiven = NOT_GIVEN, + agent_type: Literal['voice', 'text'] | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + provider: str | None | NotGiven = NOT_GIVEN, + api_key: str | None | NotGiven = NOT_GIVEN, + assistant_id: str | None | NotGiven = NOT_GIVEN, + authentication_method: Literal['api_key'] | None | NotGiven = NOT_GIVEN, + language: str | None | NotGiven = NOT_GIVEN, + languages: list[str] | None | NotGiven = NOT_GIVEN, + contact_number: str | None | NotGiven = NOT_GIVEN, + inbound: bool | None | NotGiven = NOT_GIVEN, + target_speaks_first: bool | None | NotGiven = NOT_GIVEN, + knowledge_base: str | None | NotGiven = NOT_GIVEN, + model: str | None | NotGiven = NOT_GIVEN, + model_details: dict[str, Any] | None | NotGiven = NOT_GIVEN, + websocket_url: str | None | NotGiven = NOT_GIVEN, + websocket_headers: dict[str, Any] | None | NotGiven = NOT_GIVEN, + livekit_url: str | None | NotGiven = NOT_GIVEN, + livekit_api_key: str | None | NotGiven = NOT_GIVEN, + livekit_api_secret: str | None | NotGiven = NOT_GIVEN, + livekit_agent_name: str | None | NotGiven = NOT_GIVEN, + livekit_config_json: dict[str, Any] | None | NotGiven = NOT_GIVEN, + livekit_max_concurrency: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.AgentDefinitionEditResponse +``` + +```typescript TypeScript +client.agents.update(agentId: string, params: AgentsUpdateParams = {}, options?: RequestOptions): Promise + +export interface AgentsUpdateParams { + observability_enabled?: boolean | null; + agent_name?: string | null; + agent_type?: "voice" | "text" | null; + description?: string | null; + provider?: string | null; + api_key?: string | null; + assistant_id?: string | null; + authentication_method?: "api_key" | null; + language?: string | null; + languages?: Array | null; + contact_number?: string | null; + inbound?: boolean | null; + target_speaks_first?: boolean | null; + knowledge_base?: string | null; + model?: string | null; + model_details?: Record | null; + websocket_url?: string | null; + websocket_headers?: Record | null; + livekit_url?: string | null; + livekit_api_key?: string | null; + livekit_api_secret?: string | null; + livekit_agent_name?: string | null; + livekit_config_json?: Record | null; + livekit_max_concurrency?: number | null; +} +``` + + + +#### Parameters + + + Positional argument `agent_id`. + + + + + + + + + + + + + + + + + + + + + + + + + + +#### Returns + +[`AgentDefinitionEditResponse`](/docs/sdk/reference/simulation-models#agentdefinitioneditresponse). + +## client.agents.versions + +TypeScript: `client.agents.versions`. + +### agents.versions.create + +Snapshot agent configuration into a new version and activate it. Can also update agent configuration. Use the returned version when creating a simulation test; existing tests may remain pinned to an older version. + + + +**MCP tool**: `create_agent_version` + + + +```python Python +result = client.agents.versions.create("your-agent-id") +``` + +```typescript TypeScript +const result = await client.agents.versions.create("your-agent-id"); +``` + + + + + +```python Python +client.agents.versions.create( + agent_id: str, + *, + agent_name: str | None | NotGiven = NOT_GIVEN, + agent_type: Literal['voice', 'text'] | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + provider: str | None | NotGiven = NOT_GIVEN, + api_key: str | None | NotGiven = NOT_GIVEN, + assistant_id: str | None | NotGiven = NOT_GIVEN, + authentication_method: Literal['api_key'] | None | NotGiven = NOT_GIVEN, + language: str | None | NotGiven = NOT_GIVEN, + languages: list[str] | None | NotGiven = NOT_GIVEN, + contact_number: str | None | NotGiven = NOT_GIVEN, + inbound: bool | None | NotGiven = NOT_GIVEN, + target_speaks_first: bool | None | NotGiven = NOT_GIVEN, + knowledge_base: str | None | NotGiven = NOT_GIVEN, + model: str | None | NotGiven = NOT_GIVEN, + model_details: dict[str, Any] | None | NotGiven = NOT_GIVEN, + livekit_url: str | None | NotGiven = NOT_GIVEN, + livekit_api_key: str | None | NotGiven = NOT_GIVEN, + livekit_api_secret: str | None | NotGiven = NOT_GIVEN, + livekit_agent_name: str | None | NotGiven = NOT_GIVEN, + livekit_config_json: dict[str, Any] | None | NotGiven = NOT_GIVEN, + livekit_max_concurrency: int | None | NotGiven = NOT_GIVEN, + commit_message: str | None | NotGiven = NOT_GIVEN, + observability_enabled: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.AgentVersionCreateResponse +``` + +```typescript TypeScript +client.agents.versions.create(agentId: string, params: AgentsVersionsCreateParams = {}, options?: RequestOptions): Promise + +export interface AgentsVersionsCreateParams { + agent_name?: string | null; + agent_type?: "voice" | "text" | null; + description?: string | null; + provider?: string | null; + api_key?: string | null; + assistant_id?: string | null; + authentication_method?: "api_key" | null; + language?: string | null; + languages?: Array | null; + contact_number?: string | null; + inbound?: boolean | null; + target_speaks_first?: boolean | null; + knowledge_base?: string | null; + model?: string | null; + model_details?: Record | null; + livekit_url?: string | null; + livekit_api_key?: string | null; + livekit_api_secret?: string | null; + livekit_agent_name?: string | null; + livekit_config_json?: Record | null; + livekit_max_concurrency?: number | null; + commit_message?: string | null; + observability_enabled?: boolean | null; +} +``` + + + +#### Parameters + + + Positional argument `agent_id`. + + + + + + + + + + + + + + + + + + + + + + + + + +#### Returns + +[`AgentVersionCreateResponse`](/docs/sdk/reference/simulation-models#agentversioncreateresponse). diff --git a/src/pages/docs/sdk/reference/alerts.mdx b/src/pages/docs/sdk/reference/alerts.mdx new file mode 100644 index 000000000..173e4c8d8 --- /dev/null +++ b/src/pages/docs/sdk/reference/alerts.mdx @@ -0,0 +1,153 @@ +--- +title: "Alerts" +description: "Reference for client.alerts in the Future AGI Python and TypeScript SDKs: alerts.logs.list, alerts.rules.list." +--- + +`client.alerts` on `fi.Client` (Python) and `client.alerts` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.alerts.logs`, `client.alerts.rules`. The models these methods return are on [Observability response models](/docs/sdk/reference/observability-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`alerts.logs.list`](#alertslogslist) | List alerts that have fired in numbered pages. | +| [`alerts.rules.list`](#alertsruleslist) | List the configured alert monitors - what each one watches, its threshold and its project. | + +## client.alerts + +## client.alerts.logs + +TypeScript: `client.alerts.logs`. + +### alerts.logs.list + +List alerts that have fired in numbered pages. Use this to find out what the platform has already flagged before digging into traces or error clusters. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_fired_alerts` + + + +```python Python +for item in client.alerts.logs.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.alerts.logs.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.alerts.logs.list( + *, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.UserAlertMonitorLog] +``` + +```typescript TypeScript +client.alerts.logs.list(params: AlertsLogsListParams = {}, options?: RequestOptions): Pager + +export interface AlertsLogsListParams { + /** Number of results to return per page. */ + limit?: number | null; +} +``` + + + +#### Parameters + + + Number of results to return per page. + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`UserAlertMonitorLog`](/docs/sdk/reference/observability-models#useralertmonitorlog) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +## client.alerts.rules + +TypeScript: `client.alerts.rules`. + +### alerts.rules.list + +List the configured alert monitors - what each one watches, its threshold and its project. Pair with list_fired_alerts to explain why an alert fired, or to see that no monitor covers a condition the user expected to be caught. + + + +**MCP tool**: `list_alert_rules` + + + +```python Python +result = client.alerts.rules.list() +``` + +```typescript TypeScript +const result = await client.alerts.rules.list(); +``` + + + + + +```python Python +client.alerts.rules.list( + *, + page_number: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + search_text: str | None | NotGiven = NOT_GIVEN, + project_id: list[str] | None | NotGiven = NOT_GIVEN, + status: list[Literal['triggered', 'healthy']] | None | NotGiven = NOT_GIVEN, + metric_type: list[str] | None | NotGiven = NOT_GIVEN, + sort_by: str | None | NotGiven = NOT_GIVEN, + sort_direction: Literal['asc', 'desc'] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.UserAlertMonitorListResult +``` + +```typescript TypeScript +client.alerts.rules.list(params: AlertsRulesListParams = {}, options?: RequestOptions): Promise + +export interface AlertsRulesListParams { + /** Zero-based page number. */ + page_number?: number | null; + page_size?: number | null; + search_text?: string | null; + project_id?: Array | null; + status?: Array<"triggered" | "healthy"> | null; + metric_type?: Array | null; + sort_by?: string | null; + sort_direction?: "asc" | "desc" | null; +} +``` + + + +#### Parameters + + + Zero-based page number. + + + + + + + + + +#### Returns + +[`UserAlertMonitorListResult`](/docs/sdk/reference/observability-models#useralertmonitorlistresult). diff --git a/src/pages/docs/sdk/reference/annotation-models.mdx b/src/pages/docs/sdk/reference/annotation-models.mdx new file mode 100644 index 000000000..01ef5094d --- /dev/null +++ b/src/pages/docs/sdk/reference/annotation-models.mdx @@ -0,0 +1,41 @@ +--- +title: "Annotation response models" +description: "The 30 response models returned by the annotation resources of the Future AGI Python and TypeScript SDKs, with every field and its type." +--- + +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)). + +## Models + +| Model | Fields | +|---|---| +| `AnnotationQueue` | `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` | +| `AnnotationsLabels` | `id: string`, `name: string`, `type: string`, `organization: string`, `settings: any`, `project: string`, `description: string`, `allow_notes: boolean`, `created_at: string`, `trace_annotations_count: integer`, `annotation_count: integer`, `archived: boolean` | +| `BulkAnnotationResponseResult` | `message: string`, `annotations_created: integer`, `annotations_updated: integer`, `notes_created: integer`, `succeeded_count: integer`, `errors_count: integer`, `warnings_count: integer`, `warnings: any[]`, `errors: any[]` | +| `BulkCreateScoresResult` | `scores:` [`Score`](#score)[], `errors: string[]` | +| `QueueAddItemsResult` | `added: integer`, `duplicates: integer`, `errors: string[]`, `queue_status: string`, `total_matching: integer`, `total_matching_is_lower_bound: boolean`, `has_more: boolean`, `next_cursor: string`, `next_cursor_fingerprint: string` | +| `QueueAddLabelResult` | `label:` [`QueueLabelResult`](#queuelabelresult), `created: boolean`, `reopened_items: integer`, `queue_status: string` | +| `QueueAgreementAnnotatorPair` | `annotator_1_id: string`, `annotator_2_id: string`, `agreement_pct: number`, `total_comparisons: integer` | +| `QueueAgreementLabel` | `label_name: string`, `label_type: string`, `agreement_pct: number`, `cohens_kappa: number`, `disagreement_count: integer`, `disagreement_items: string[]` | +| `QueueAgreementResult` | `overall_agreement: number`, `labels: any`, `annotator_pairs:` [`QueueAgreementAnnotatorPair`](#queueagreementannotatorpair)[] | +| `QueueAnalyticsAnnotatorPerformance` | `user_id: string`, `name: string`, `completed: integer`, `last_active: string` | +| `QueueAnalyticsResult` | `throughput:` [`QueueAnalyticsThroughput`](#queueanalyticsthroughput), `annotator_performance:` [`QueueAnalyticsAnnotatorPerformance`](#queueanalyticsannotatorperformance)[], `label_distribution: any`, `status_breakdown: any`, `total: integer` | +| `QueueAnalyticsThroughput` | `daily:` [`QueueAnalyticsThroughputDaily`](#queueanalyticsthroughputdaily)[], `total_completed: integer`, `avg_per_day: number` | +| `QueueAnalyticsThroughputDaily` | `date: string`, `count: integer` | +| `QueueAnnotateDetailResult` | `item: any`, `queue: any`, `labels: any[]`, `annotations: any[]`, `review_comments: any[]`, `review_threads: any[]`, `existing_notes: string`, `span_notes: any[]`, `span_notes_source_id: string`, `progress: any`, `next_item_id: string`, `prev_item_id: string` | +| `QueueAnnotatorNested` | `id: string`, `user_id: string`, `name: string`, `email: string`, `role: string`, `roles: string[]` | +| `QueueAssignItemsResult` | `assigned: integer` | +| `QueueBulkRemoveItemsResult` | `removed: integer` | +| `QueueExportToDatasetResult` | `dataset_id: string`, `dataset_name: string`, `rows_created: integer`, `columns: string[]` | +| `QueueImportAnnotationsResult` | `imported: integer` | +| `QueueItem` | `id: string`, `queue: string`, `source_type: string`, `source_id: string`, `status: string`, `workflow_status: any`, `workflow_status_label: any`, `priority: integer`, `order: integer`, `metadata: any`, `assigned_to: string`, `assigned_to_name: string`, `assigned_users:` [`QueueItemAssignedUser`](#queueitemassigneduser)[], `reserved_by: string`, `reserved_by_name: string`, `reservation_expires_at: string`, `review_status: string`, `reviewed_by: string`, `reviewed_by_name: string`, `reviewed_at: string`, `review_notes: string`, `source_preview: any JSON value`, `comment_count: integer`, `open_feedback_count: integer`, `created_at: string` | +| `QueueItemAssignedUser` | `id: string`, `name: string`, `email: string` | +| `QueueLabelNested` | `id: string`, `label_id: string`, `name: string`, `type: string`, `required: boolean`, `order: integer` | +| `QueueLabelResult` | `id: string`, `name: string`, `type: string`, `settings: any`, `description: string`, `allow_notes: boolean`, `required: boolean`, `order: integer` | +| `QueueNavigationResult` | `completed_item_id: string`, `skipped_item_id: string`, `next_item: any` | +| `QueueProgressAnnotatorStat` | `user_id: string`, `name: string`, `completed: integer`, `pending: integer`, `in_progress: integer`, `in_review: integer`, `annotations_count: integer` | +| `QueueProgressResult` | `total: integer`, `pending: integer`, `in_progress: integer`, `in_review: integer`, `completed: integer`, `skipped: integer`, `progress_pct: number`, `annotator_stats:` [`QueueProgressAnnotatorStat`](#queueprogressannotatorstat)[], `user_progress:` [`QueueProgressUserProgress`](#queueprogressuserprogress) | +| `QueueProgressUserProgress` | `total: integer`, `completed: integer`, `pending: integer`, `in_progress: integer`, `in_review: integer`, `skipped: integer`, `progress_pct: number` | +| `QueueRemoveLabelResult` | `removed: boolean` | +| `QueueSubmitAnnotationsResult` | `submitted: integer` | +| `Score` | `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` | diff --git a/src/pages/docs/sdk/reference/annotation-queues.mdx b/src/pages/docs/sdk/reference/annotation-queues.mdx new file mode 100644 index 000000000..671a47ddb --- /dev/null +++ b/src/pages/docs/sdk/reference/annotation-queues.mdx @@ -0,0 +1,1405 @@ +--- +title: "Annotation queues" +description: "Reference for client.annotation_queues in the Future AGI Python and TypeScript SDKs: annotation_queues.add_label, annotation_queues.agreement, annotation_queues.analytics, annotation_queues.create, annotation_queues.delete, annotation_queues.export and 17 more." +--- + +`client.annotation_queues` on `fi.Client` (Python) and `client.annotationQueues` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.annotation_queues.items`. The models these methods return are on [Annotation response models](/docs/sdk/reference/annotation-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`annotation_queues.add_label`](#annotation_queuesadd_label) | Add an annotation label to a queue. | +| [`annotation_queues.agreement`](#annotation_queuesagreement) | Inter-annotator agreement for a queue. | +| [`annotation_queues.analytics`](#annotation_queuesanalytics) | Throughput, annotator performance and label distribution for a queue. | +| [`annotation_queues.create`](#annotation_queuescreate) | Create an annotation queue with its labels and annotators. | +| [`annotation_queues.delete`](#annotation_queuesdelete) | Delete an annotation queue. | +| [`annotation_queues.export`](#annotation_queuesexport) | Export a queue's annotations, as JSON or, with `export_format=csv`, as CSV text. | +| [`annotation_queues.export_to_dataset`](#annotation_queuesexport_to_dataset) | Write a queue's annotations into a new or existing dataset. | +| [`annotation_queues.get`](#annotation_queuesget) | Return an annotation queue by its identifier. | +| [`annotation_queues.list`](#annotation_queueslist) | List annotation queues in the current workspace. | +| [`annotation_queues.progress`](#annotation_queuesprogress) | Item counts by status and per-annotator progress for a queue. | +| [`annotation_queues.remove_label`](#annotation_queuesremove_label) | Remove an annotation label from a queue. | +| [`annotation_queues.update`](#annotation_queuesupdate) | Update selected fields of an annotation queue. | +| [`annotation_queues.update_status`](#annotation_queuesupdate_status) | Change a queue's status (draft, active, paused, completed, archived). | +| [`annotation_queues.items.add`](#annotation_queuesitemsadd) | Add items (spans, traces, dataset rows) to a queue, by id or by a selection filter. | +| [`annotation_queues.items.annotate_detail`](#annotation_queuesitemsannotate_detail) | Return everything needed to annotate one queue item; reserve=true acquires an editing reservation for the caller. | +| [`annotation_queues.items.assign`](#annotation_queuesitemsassign) | Assign or unassign queue items to annotators. | +| [`annotation_queues.items.complete`](#annotation_queuesitemscomplete) | Mark an annotated queue item complete and return the next item to work on. | +| [`annotation_queues.items.import_annotations`](#annotation_queuesitemsimport_annotations) | Import existing annotations onto a queue item, optionally on behalf of an annotator. | +| [`annotation_queues.items.list`](#annotation_queuesitemslist) | List items belonging to an annotation queue. | +| [`annotation_queues.items.list_annotations`](#annotation_queuesitemslist_annotations) | List the annotations recorded on a queue item. | +| [`annotation_queues.items.remove`](#annotation_queuesitemsremove) | Remove items from a queue. | +| [`annotation_queues.items.skip`](#annotation_queuesitemsskip) | Skip a queue item and return the next one to work on. | +| [`annotation_queues.items.submit`](#annotation_queuesitemssubmit) | Submit annotation values for an item in an annotation queue. | + +## client.annotation_queues + +### annotation_queues.add_label + +Add an annotation label to a queue. + + + + + +```python Python +result = client.annotation_queues.add_label("your-id", label_id="your-label-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.addLabel("your-id", { label_id: "your-label-id" }); +``` + + + + + +```python Python +client.annotation_queues.add_label( + id: str, + *, + label_id: str, + required: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueAddLabelResult +``` + +```typescript TypeScript +client.annotationQueues.addLabel(id: string, params: AnnotationQueuesAddLabelParams, options?: RequestOptions): Promise + +export interface AnnotationQueuesAddLabelParams { + label_id: string; + required?: boolean | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + + + +#### Returns + +[`QueueAddLabelResult`](/docs/sdk/reference/annotation-models#queueaddlabelresult). + +### annotation_queues.agreement + +Inter-annotator agreement for a queue. + + + + + +```python Python +result = client.annotation_queues.agreement("your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.agreement("your-id"); +``` + + + + + +```python Python +client.annotation_queues.agreement( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueAgreementResult +``` + +```typescript TypeScript +client.annotationQueues.agreement(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + +#### Returns + +[`QueueAgreementResult`](/docs/sdk/reference/annotation-models#queueagreementresult). + +### annotation_queues.analytics + +Throughput, annotator performance and label distribution for a queue. + + + + + +```python Python +result = client.annotation_queues.analytics("your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.analytics("your-id"); +``` + + + + + +```python Python +client.annotation_queues.analytics( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueAnalyticsResult +``` + +```typescript TypeScript +client.annotationQueues.analytics(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + +#### Returns + +[`QueueAnalyticsResult`](/docs/sdk/reference/annotation-models#queueanalyticsresult). + +### annotation_queues.create + +Create an annotation queue with its labels and annotators. + + + + + +```python Python +result = client.annotation_queues.create(name="your-name", label_ids=[]) +``` + +```typescript TypeScript +const result = await client.annotationQueues.create({ + name: "your-name", + label_ids: [], +}); +``` + + + + + +```python Python +client.annotation_queues.create( + *, + name: str, + label_ids: list[str], + description: str | None | NotGiven = NOT_GIVEN, + instructions: str | None | NotGiven = NOT_GIVEN, + assignment_strategy: Literal['manual', 'round_robin', 'load_balanced'] | None | NotGiven = NOT_GIVEN, + annotations_required: int | None | NotGiven = NOT_GIVEN, + reservation_timeout_minutes: int | None | NotGiven = NOT_GIVEN, + requires_review: bool | None | NotGiven = NOT_GIVEN, + auto_assign: bool | None | NotGiven = NOT_GIVEN, + annotator_ids: list[str] | None | NotGiven = NOT_GIVEN, + annotator_roles: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.AnnotationQueue +``` + +```typescript TypeScript +client.annotationQueues.create(params: AnnotationQueuesCreateParams, options?: RequestOptions): Promise + +export interface AnnotationQueuesCreateParams { + name: string; + label_ids: Array; + description?: string | null; + instructions?: string | null; + assignment_strategy?: "manual" | "round_robin" | "load_balanced" | null; + annotations_required?: number | null; + reservation_timeout_minutes?: number | null; + requires_review?: boolean | null; + auto_assign?: boolean | null; + annotator_ids?: Array | null; + annotator_roles?: Record | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + + +#### Returns + +[`AnnotationQueue`](/docs/sdk/reference/annotation-models#annotationqueue). + +### annotation_queues.delete + +Delete an annotation queue. + + + + + +```python Python +result = client.annotation_queues.delete("your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.delete("your-id"); +``` + + + + + +```python Python +client.annotation_queues.delete( + id: str, + *, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.annotationQueues.delete(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### annotation_queues.export + +Export a queue's annotations, as JSON or, with `export_format=csv`, as CSV text. + + + + + +```python Python +result = client.annotation_queues.export("your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.export("your-id"); +``` + + + + + +```python Python +client.annotation_queues.export( + id: str, + *, + export_format: Literal['json', 'csv'] | None | NotGiven = NOT_GIVEN, + status: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.annotationQueues.export(id: string, params: AnnotationQueuesExportParams = {}, options?: RequestOptions): Promise + +export interface AnnotationQueuesExportParams { + export_format?: "json" | "csv" | null; + status?: string | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + + + +#### Returns + +The decoded JSON when the response is JSON, else the body as text. + +### annotation_queues.export_to_dataset + +Write a queue's annotations into a new or existing dataset. + + + + + +```python Python +result = client.annotation_queues.export_to_dataset("your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.exportToDataset("your-id"); +``` + + + + + +```python Python +client.annotation_queues.export_to_dataset( + id: str, + *, + dataset_id: str | None | NotGiven = NOT_GIVEN, + dataset_name: str | None | NotGiven = NOT_GIVEN, + status_filter: str | None | NotGiven = NOT_GIVEN, + column_mapping: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueExportToDatasetResult +``` + +```typescript TypeScript +client.annotationQueues.exportToDataset(id: string, params: AnnotationQueuesExportToDatasetParams = {}, options?: RequestOptions): Promise + +export interface AnnotationQueuesExportToDatasetParams { + dataset_id?: string | null; + dataset_name?: string | null; + status_filter?: string | null; + column_mapping?: Array> | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + + + + + +#### Returns + +[`QueueExportToDatasetResult`](/docs/sdk/reference/annotation-models#queueexporttodatasetresult). + +### annotation_queues.get + +Return an annotation queue by its identifier. + + + +**MCP tool**: `get_annotation_queue` + + + +```python Python +result = client.annotation_queues.get("your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.get("your-id"); +``` + + + + + +```python Python +client.annotation_queues.get( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.AnnotationQueue +``` + +```typescript TypeScript +client.annotationQueues.get(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + +#### Returns + +[`AnnotationQueue`](/docs/sdk/reference/annotation-models#annotationqueue). + +### annotation_queues.list + +List annotation queues in the current workspace. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_annotation_queues` + + + +```python Python +for item in client.annotation_queues.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.annotationQueues.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.annotation_queues.list( + *, + limit: int | None | NotGiven = NOT_GIVEN, + status: str | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + include_counts: bool | None | NotGiven = NOT_GIVEN, + archived: bool | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.AnnotationQueue] +``` + +```typescript TypeScript +client.annotationQueues.list(params: AnnotationQueuesListParams = {}, options?: RequestOptions): Pager + +export interface AnnotationQueuesListParams { + /** Number of results to return per page. */ + limit?: number | null; + status?: string | null; + search?: string | null; + include_counts?: boolean | null; + archived?: boolean | null; + page_size?: number | null; +} +``` + + + +#### Parameters + + + Number of results to return per page. + + + + + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`AnnotationQueue`](/docs/sdk/reference/annotation-models#annotationqueue) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### annotation_queues.progress + +Item counts by status and per-annotator progress for a queue. + + + + + +```python Python +result = client.annotation_queues.progress("your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.progress("your-id"); +``` + + + + + +```python Python +client.annotation_queues.progress( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueProgressResult +``` + +```typescript TypeScript +client.annotationQueues.progress(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + +#### Returns + +[`QueueProgressResult`](/docs/sdk/reference/annotation-models#queueprogressresult). + +### annotation_queues.remove_label + +Remove an annotation label from a queue. + + + + + +```python Python +result = client.annotation_queues.remove_label("your-id", label_id="your-label-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.removeLabel("your-id", { label_id: "your-label-id" }); +``` + + + + + +```python Python +client.annotation_queues.remove_label( + id: str, + *, + label_id: str, + required: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueRemoveLabelResult +``` + +```typescript TypeScript +client.annotationQueues.removeLabel(id: string, params: AnnotationQueuesRemoveLabelParams, options?: RequestOptions): Promise + +export interface AnnotationQueuesRemoveLabelParams { + label_id: string; + required?: boolean | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + + + +#### Returns + +[`QueueRemoveLabelResult`](/docs/sdk/reference/annotation-models#queueremovelabelresult). + +### annotation_queues.update + +Update selected fields of an annotation queue. + + + + + +```python Python +result = client.annotation_queues.update("your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.update("your-id"); +``` + + + + + +```python Python +client.annotation_queues.update( + id: str, + *, + name: str | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + instructions: str | None | NotGiven = NOT_GIVEN, + assignment_strategy: Literal['manual', 'round_robin', 'load_balanced'] | None | NotGiven = NOT_GIVEN, + annotations_required: int | None | NotGiven = NOT_GIVEN, + reservation_timeout_minutes: int | None | NotGiven = NOT_GIVEN, + requires_review: bool | None | NotGiven = NOT_GIVEN, + auto_assign: bool | None | NotGiven = NOT_GIVEN, + label_ids: list[str] | None | NotGiven = NOT_GIVEN, + annotator_ids: list[str] | None | NotGiven = NOT_GIVEN, + annotator_roles: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.AnnotationQueue +``` + +```typescript TypeScript +client.annotationQueues.update(id: string, params: AnnotationQueuesUpdateParams = {}, options?: RequestOptions): Promise + +export interface AnnotationQueuesUpdateParams { + name?: string | null; + description?: string | null; + instructions?: string | null; + assignment_strategy?: "manual" | "round_robin" | "load_balanced" | null; + annotations_required?: number | null; + reservation_timeout_minutes?: number | null; + requires_review?: boolean | null; + auto_assign?: boolean | null; + label_ids?: Array | null; + annotator_ids?: Array | null; + annotator_roles?: Record | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + + + + + + + + + + + + +#### Returns + +[`AnnotationQueue`](/docs/sdk/reference/annotation-models#annotationqueue). + +### annotation_queues.update_status + +Change a queue's status (draft, active, paused, completed, archived). + + + + + +```python Python +result = client.annotation_queues.update_status("your-id", status="draft") +``` + +```typescript TypeScript +const result = await client.annotationQueues.updateStatus("your-id", { status: "draft" }); +``` + + + + + +```python Python +client.annotation_queues.update_status( + id: str, + *, + status: Literal['draft', 'active', 'paused', 'completed'], + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.AnnotationQueue +``` + +```typescript TypeScript +client.annotationQueues.updateStatus(id: string, params: AnnotationQueuesUpdateStatusParams, options?: RequestOptions): Promise + +export interface AnnotationQueuesUpdateStatusParams { + status: "draft" | "active" | "paused" | "completed"; +} +``` + + + +#### Parameters + + + A UUID string identifying this annotation queue. + + + +#### Returns + +[`AnnotationQueue`](/docs/sdk/reference/annotation-models#annotationqueue). + +## client.annotation_queues.items + +TypeScript: `client.annotationQueues.items`. + +### annotation_queues.items.add + +Add items (spans, traces, dataset rows) to a queue, by id or by a selection filter. + + + + + +```python Python +result = client.annotation_queues.items.add("your-queue-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.items.add("your-queue-id"); +``` + + + + + +```python Python +client.annotation_queues.items.add( + queue_id: str, + *, + items: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + selection: dict[str, Any] | None | NotGiven = NOT_GIVEN, + project_id: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueAddItemsResult +``` + +```typescript TypeScript +client.annotationQueues.items.add(queueId: string, params: AnnotationQueuesItemsAddParams = {}, options?: RequestOptions): Promise + +export interface AnnotationQueuesItemsAddParams { + items?: Array> | null; + selection?: Record | null; + project_id?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `queue_id`. + + + + + +#### Returns + +[`QueueAddItemsResult`](/docs/sdk/reference/annotation-models#queueadditemsresult). + +### annotation_queues.items.annotate_detail + +Return everything needed to annotate one queue item; reserve=true acquires an editing reservation for the caller. Includes its source content, the queue instructions, every label with its settings (the allowed values a submitted value must match), any annotations already recorded, and the next/previous item ids. Call this before submit_annotation; the label settings are not available anywhere else. + + + +**MCP tool**: `get_annotation_item_detail` + + + +```python Python +result = client.annotation_queues.items.annotate_detail("your-queue-id", "your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.items.annotateDetail("your-queue-id", "your-id"); +``` + + + + + +```python Python +client.annotation_queues.items.annotate_detail( + queue_id: str, + id: str, + *, + annotator_id: str | None | NotGiven = NOT_GIVEN, + include_completed: bool | None | NotGiven = NOT_GIVEN, + view_mode: str | None | NotGiven = NOT_GIVEN, + review_status: str | None | NotGiven = NOT_GIVEN, + exclude_review_status: str | None | NotGiven = NOT_GIVEN, + include_all_annotations: bool | None | NotGiven = NOT_GIVEN, + reserve: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueAnnotateDetailResult +``` + +```typescript TypeScript +client.annotationQueues.items.annotateDetail(queueId: string, id: string, params: AnnotationQueuesItemsAnnotateDetailParams = {}, options?: RequestOptions): Promise + +export interface AnnotationQueuesItemsAnnotateDetailParams { + annotator_id?: string | null; + include_completed?: boolean | null; + view_mode?: string | null; + review_status?: string | null; + exclude_review_status?: string | null; + include_all_annotations?: boolean | null; + reserve?: boolean | null; +} +``` + + + +#### Parameters + + + Positional argument `queue_id`. + + + A UUID string identifying this queue item. + + + + + + + + + +#### Returns + +[`QueueAnnotateDetailResult`](/docs/sdk/reference/annotation-models#queueannotatedetailresult). + +### annotation_queues.items.assign + +Assign or unassign queue items to annotators. + + + + + +```python Python +result = client.annotation_queues.items.assign("your-queue-id", item_ids=[]) +``` + +```typescript TypeScript +const result = await client.annotationQueues.items.assign("your-queue-id", { item_ids: [] }); +``` + + + + + +```python Python +client.annotation_queues.items.assign( + queue_id: str, + *, + item_ids: list[str], + user_ids: list[str] | None | NotGiven = NOT_GIVEN, + action: Literal['add', 'set', 'remove'] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueAssignItemsResult +``` + +```typescript TypeScript +client.annotationQueues.items.assign(queueId: string, params: AnnotationQueuesItemsAssignParams, options?: RequestOptions): Promise + +export interface AnnotationQueuesItemsAssignParams { + item_ids: Array; + user_ids?: Array | null; + action?: "add" | "set" | "remove" | null; +} +``` + + + +#### Parameters + + + Positional argument `queue_id`. + + + + + +#### Returns + +[`QueueAssignItemsResult`](/docs/sdk/reference/annotation-models#queueassignitemsresult). + +### annotation_queues.items.complete + +Mark an annotated queue item complete and return the next item to work on. Required to finish an item - submit_annotation alone leaves it in_progress and the queue never closes. + + + +**MCP tool**: `complete_annotation_item` + + + +```python Python +result = client.annotation_queues.items.complete("your-queue-id", "your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.items.complete("your-queue-id", "your-id"); +``` + + + + + +```python Python +client.annotation_queues.items.complete( + queue_id: str, + id: str, + *, + exclude: list[str] | None | NotGiven = NOT_GIVEN, + exclude_review_status: str | None | NotGiven = NOT_GIVEN, + include_completed: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueNavigationResult +``` + +```typescript TypeScript +client.annotationQueues.items.complete(queueId: string, id: string, params: AnnotationQueuesItemsCompleteParams = {}, options?: RequestOptions): Promise + +export interface AnnotationQueuesItemsCompleteParams { + exclude?: Array | null; + exclude_review_status?: string | null; + include_completed?: boolean | null; +} +``` + + + +#### Parameters + + + Positional argument `queue_id`. + + + A UUID string identifying this queue item. + + + + + +#### Returns + +[`QueueNavigationResult`](/docs/sdk/reference/annotation-models#queuenavigationresult). + +### annotation_queues.items.import_annotations + +Import existing annotations onto a queue item, optionally on behalf of an annotator. + + + + + +```python Python +result = client.annotation_queues.items.import_annotations( + "your-queue-id", + "your-id", + annotations=[], +) +``` + +```typescript TypeScript +const result = await client.annotationQueues.items.importAnnotations("your-queue-id", "your-id", { annotations: [] }); +``` + + + + + +```python Python +client.annotation_queues.items.import_annotations( + queue_id: str, + id: str, + *, + annotations: list[dict[str, Any]], + annotator_id: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueImportAnnotationsResult +``` + +```typescript TypeScript +client.annotationQueues.items.importAnnotations(queueId: string, id: string, params: AnnotationQueuesItemsImportAnnotationsParams, options?: RequestOptions): Promise + +export interface AnnotationQueuesItemsImportAnnotationsParams { + annotations: Array>; + annotator_id?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `queue_id`. + + + A UUID string identifying this queue item. + + + + +#### Returns + +[`QueueImportAnnotationsResult`](/docs/sdk/reference/annotation-models#queueimportannotationsresult). + +### annotation_queues.items.list + +List items belonging to an annotation queue. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_annotation_queue_items` + + + +```python Python +for item in client.annotation_queues.items.list("your-queue-id"): + print(item) +``` + +```typescript TypeScript +for await (const item of client.annotationQueues.items.list("your-queue-id")) { + console.log(item); +} +``` + + + + + +```python Python +client.annotation_queues.items.list( + queue_id: str, + *, + limit: int | None | NotGiven = NOT_GIVEN, + status: list[str] | None | NotGiven = NOT_GIVEN, + source_type: list[str] | None | NotGiven = NOT_GIVEN, + assigned_to: str | None | NotGiven = NOT_GIVEN, + review_status: str | None | NotGiven = NOT_GIVEN, + ordering: Literal['created_at', '-created_at'] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.QueueItem] +``` + +```typescript TypeScript +client.annotationQueues.items.list(queueId: string, params: AnnotationQueuesItemsListParams = {}, options?: RequestOptions): Pager + +export interface AnnotationQueuesItemsListParams { + /** Number of results to return per page. */ + limit?: number | null; + status?: Array | null; + source_type?: Array | null; + assigned_to?: string | null; + review_status?: string | null; + ordering?: "created_at" | "-created_at" | null; +} +``` + + + +#### Parameters + + + Positional argument `queue_id`. + + + Number of results to return per page. + + + + + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`QueueItem`](/docs/sdk/reference/annotation-models#queueitem) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### annotation_queues.items.list_annotations + +List the annotations recorded on a queue item. + + + + + +```python Python +result = client.annotation_queues.items.list_annotations("your-queue-id", "your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.items.listAnnotations("your-queue-id", "your-id"); +``` + + + + + +```python Python +client.annotation_queues.items.list_annotations( + queue_id: str, + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> List[models.Score] +``` + +```typescript TypeScript +client.annotationQueues.items.listAnnotations(queueId: string, id: string, options?: RequestOptions): Promise> +``` + + + +#### Parameters + + + Positional argument `queue_id`. + + + A UUID string identifying this queue item. + + +#### Returns + +A list of [`Score`](/docs/sdk/reference/annotation-models#score). + +### annotation_queues.items.remove + +Remove items from a queue. + + + + + +```python Python +result = client.annotation_queues.items.remove("your-queue-id", item_ids=[]) +``` + +```typescript TypeScript +const result = await client.annotationQueues.items.remove("your-queue-id", { item_ids: [] }); +``` + + + + + +```python Python +client.annotation_queues.items.remove( + queue_id: str, + *, + item_ids: list[str], + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueBulkRemoveItemsResult +``` + +```typescript TypeScript +client.annotationQueues.items.remove(queueId: string, params: AnnotationQueuesItemsRemoveParams, options?: RequestOptions): Promise + +export interface AnnotationQueuesItemsRemoveParams { + item_ids: Array; +} +``` + + + +#### Parameters + + + Positional argument `queue_id`. + + + +#### Returns + +[`QueueBulkRemoveItemsResult`](/docs/sdk/reference/annotation-models#queuebulkremoveitemsresult). + +### annotation_queues.items.skip + +Skip a queue item and return the next one to work on. + + + + + +```python Python +result = client.annotation_queues.items.skip("your-queue-id", "your-id") +``` + +```typescript TypeScript +const result = await client.annotationQueues.items.skip("your-queue-id", "your-id"); +``` + + + + + +```python Python +client.annotation_queues.items.skip( + queue_id: str, + id: str, + *, + exclude: list[str] | None | NotGiven = NOT_GIVEN, + exclude_review_status: str | None | NotGiven = NOT_GIVEN, + include_completed: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueNavigationResult +``` + +```typescript TypeScript +client.annotationQueues.items.skip(queueId: string, id: string, params: AnnotationQueuesItemsSkipParams = {}, options?: RequestOptions): Promise + +export interface AnnotationQueuesItemsSkipParams { + exclude?: Array | null; + exclude_review_status?: string | null; + include_completed?: boolean | null; +} +``` + + + +#### Parameters + + + Positional argument `queue_id`. + + + A UUID string identifying this queue item. + + + + + +#### Returns + +[`QueueNavigationResult`](/docs/sdk/reference/annotation-models#queuenavigationresult). + +### annotation_queues.items.submit + +Submit annotation values for an item in an annotation queue. The value shape must match the label's settings from get_annotation_item_detail. Submitting moves the item to in_progress only; call complete_annotation_item to finish it. + + + +**MCP tool**: `submit_annotation` + + + +```python Python +result = client.annotation_queues.items.submit( + "your-queue-id", + "your-id", + annotations=[], +) +``` + +```typescript TypeScript +const result = await client.annotationQueues.items.submit("your-queue-id", "your-id", { annotations: [] }); +``` + + + + + +```python Python +client.annotation_queues.items.submit( + queue_id: str, + id: str, + *, + annotations: list[dict[str, Any]], + notes: str | None | NotGiven = NOT_GIVEN, + item_notes: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.QueueSubmitAnnotationsResult +``` + +```typescript TypeScript +client.annotationQueues.items.submit(queueId: string, id: string, params: AnnotationQueuesItemsSubmitParams, options?: RequestOptions): Promise + +export interface AnnotationQueuesItemsSubmitParams { + annotations: Array>; + notes?: string | null; + item_notes?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `queue_id`. + + + A UUID string identifying this queue item. + + + + + +#### Returns + +[`QueueSubmitAnnotationsResult`](/docs/sdk/reference/annotation-models#queuesubmitannotationsresult). diff --git a/src/pages/docs/sdk/reference/annotations.mdx b/src/pages/docs/sdk/reference/annotations.mdx new file mode 100644 index 000000000..d1b95cf8d --- /dev/null +++ b/src/pages/docs/sdk/reference/annotations.mdx @@ -0,0 +1,305 @@ +--- +title: "Annotations" +description: "Reference for client.annotations in the Future AGI Python and TypeScript SDKs: annotations.bulk_create, annotations.labels.create, annotations.labels.delete, annotations.labels.get, annotations.labels.list." +--- + +`client.annotations` on `fi.Client` (Python) and `client.annotations` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.annotations.labels`. The models these methods return are on [Annotation response models](/docs/sdk/reference/annotation-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`annotations.bulk_create`](#annotationsbulk_create) | Create or update annotations and notes on spans in bulk. | +| [`annotations.labels.create`](#annotationslabelscreate) | Create an annotation label (text, label, score, ...) with its settings. | +| [`annotations.labels.delete`](#annotationslabelsdelete) | Delete (archive) an annotation label. | +| [`annotations.labels.get`](#annotationslabelsget) | Return an annotation label by id. | +| [`annotations.labels.list`](#annotationslabelslist) | List annotation labels, optionally filtered by project, type or search text. | + +## client.annotations + +### annotations.bulk_create + +Create or update annotations and notes on spans in bulk. + + + + + +```python Python +result = client.annotations.bulk_create(records=[]) +``` + +```typescript TypeScript +const result = await client.annotations.bulkCreate({ records: [] }); +``` + + + + + +```python Python +client.annotations.bulk_create( + *, + records: list[dict[str, Any]], + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.BulkAnnotationResponseResult +``` + +```typescript TypeScript +client.annotations.bulkCreate(params: AnnotationsBulkCreateParams, options?: RequestOptions): Promise + +export interface AnnotationsBulkCreateParams { + records: Array>; +} +``` + + + +#### Parameters + + + +#### Returns + +[`BulkAnnotationResponseResult`](/docs/sdk/reference/annotation-models#bulkannotationresponseresult). + +## client.annotations.labels + +TypeScript: `client.annotations.labels`. + +### annotations.labels.create + +Create an annotation label (text, label, score, ...) with its settings. + + + + + +```python Python +result = client.annotations.labels.create(name="your-name", type="text") +``` + +```typescript TypeScript +const result = await client.annotations.labels.create({ + name: "your-name", + type: "text", +}); +``` + + + + + +```python Python +client.annotations.labels.create( + *, + name: str, + type: Literal['text', 'numeric', 'categorical', 'star', 'thumbs_up_down'], + settings: dict[str, Any] | None | NotGiven = NOT_GIVEN, + project: str | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + allow_notes: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.AnnotationsLabels +``` + +```typescript TypeScript +client.annotations.labels.create(params: AnnotationsLabelsCreateParams, options?: RequestOptions): Promise + +export interface AnnotationsLabelsCreateParams { + name: string; + type: "text" | "numeric" | "categorical" | "star" | "thumbs_up_down"; + settings?: Record | null; + project?: string | null; + description?: string | null; + allow_notes?: boolean | null; +} +``` + + + +#### Parameters + + + + + + + + +#### Returns + +[`AnnotationsLabels`](/docs/sdk/reference/annotation-models#annotationslabels). + +### annotations.labels.delete + +Delete (archive) an annotation label. + + + + + +```python Python +result = client.annotations.labels.delete("your-id") +``` + +```typescript TypeScript +const result = await client.annotations.labels.delete("your-id"); +``` + + + + + +```python Python +client.annotations.labels.delete( + id: str, + *, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.annotations.labels.delete(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `id`. + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### annotations.labels.get + +Return an annotation label by id. + + + + + +```python Python +result = client.annotations.labels.get("your-id") +``` + +```typescript TypeScript +const result = await client.annotations.labels.get("your-id"); +``` + + + + + +```python Python +client.annotations.labels.get( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.AnnotationsLabels +``` + +```typescript TypeScript +client.annotations.labels.get(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `id`. + + +#### Returns + +[`AnnotationsLabels`](/docs/sdk/reference/annotation-models#annotationslabels). + +### annotations.labels.list + +List annotation labels, optionally filtered by project, type or search text. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) + + + +```python Python +for item in client.annotations.labels.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.annotations.labels.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.annotations.labels.list( + *, + limit: int | None | NotGiven = NOT_GIVEN, + dataset: str | None | NotGiven = NOT_GIVEN, + project_id: str | None | NotGiven = NOT_GIVEN, + type: Literal['text', 'numeric', 'categorical', 'star', 'thumbs_up_down'] | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + include_usage_count: bool | None | NotGiven = NOT_GIVEN, + include_archived: bool | None | NotGiven = NOT_GIVEN, + archived: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.AnnotationsLabels] +``` + +```typescript TypeScript +client.annotations.labels.list(params: AnnotationsLabelsListParams = {}, options?: RequestOptions): Pager + +export interface AnnotationsLabelsListParams { + /** Number of results to return per page. */ + limit?: number | null; + dataset?: string | null; + project_id?: string | null; + type?: "text" | "numeric" | "categorical" | "star" | "thumbs_up_down" | null; + search?: string | null; + include_usage_count?: boolean | null; + include_archived?: boolean | null; + archived?: boolean | null; +} +``` + + + +#### Parameters + + + Number of results to return per page. + + + + + + + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`AnnotationsLabels`](/docs/sdk/reference/annotation-models#annotationslabels) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). diff --git a/src/pages/docs/sdk/reference/dashboards.mdx b/src/pages/docs/sdk/reference/dashboards.mdx new file mode 100644 index 000000000..fb780a88c --- /dev/null +++ b/src/pages/docs/sdk/reference/dashboards.mdx @@ -0,0 +1,845 @@ +--- +title: "Dashboards" +description: "Reference for client.dashboards in the Future AGI Python and TypeScript SDKs: dashboards.create, dashboards.delete, dashboards.filter_values, dashboards.get, dashboards.list, dashboards.query and 7 more." +--- + +`client.dashboards` on `fi.Client` (Python) and `client.dashboards` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.dashboards.metrics`, `client.dashboards.widgets`. The models these methods return are on [Observability response models](/docs/sdk/reference/observability-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`dashboards.create`](#dashboardscreate) | Create an empty dashboard in the current workspace; add widgets with create_dashboard_widget. | +| [`dashboards.delete`](#dashboardsdelete) | Delete a dashboard and the widgets on it. | +| [`dashboards.filter_values`](#dashboardsfilter_values) | List the distinct values of a metric or attribute for use in dashboard filters. | +| [`dashboards.get`](#dashboardsget) | Return a dashboard and its widgets by identifier. | +| [`dashboards.list`](#dashboardslist) | List dashboards in the current workspace with their widget counts. | +| [`dashboards.query`](#dashboardsquery) | Run an ad-hoc dashboard query (time_range and metrics, with optional filters and breakdowns) and return chart data without saving a widget. | +| [`dashboards.update`](#dashboardsupdate) | Update the name and/or description of an existing dashboard (a partial update). | +| [`dashboards.metrics.list`](#dashboardsmetricslist) | List the metrics available to dashboard queries across traces, datasets, and simulations. | +| [`dashboards.widgets.create`](#dashboardswidgetscreate) | Add a widget to a dashboard. | +| [`dashboards.widgets.get`](#dashboardswidgetsget) | Return a dashboard widget, including its query_config and chart_config. | +| [`dashboards.widgets.list`](#dashboardswidgetslist) | List the widgets on a dashboard. | +| [`dashboards.widgets.query`](#dashboardswidgetsquery) | Execute a saved widget's query and return its chart data. | +| [`dashboards.widgets.update`](#dashboardswidgetsupdate) | Update selected fields on a dashboard widget, such as its query_config, chart_config, or layout. | + +## client.dashboards + +### dashboards.create + +Create an empty dashboard in the current workspace; add widgets with create_dashboard_widget. + + + +**MCP tool**: `create_dashboard` + + + +```python Python +result = client.dashboards.create(name="your-name") +``` + +```typescript TypeScript +const result = await client.dashboards.create({ name: "your-name" }); +``` + + + + + +```python Python +client.dashboards.create( + *, + name: str, + description: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardDetail +``` + +```typescript TypeScript +client.dashboards.create(params: DashboardsCreateParams, options?: RequestOptions): Promise + +export interface DashboardsCreateParams { + name: string; + description?: string | null; +} +``` + + + +#### Parameters + + + + +#### Returns + +[`DashboardDetail`](/docs/sdk/reference/observability-models#dashboarddetail). + +### dashboards.delete + +Delete a dashboard and the widgets on it. This is the only way to remove a dashboard created earlier. + + + +**MCP tool**: `delete_dashboard` + + + +```python Python +result = client.dashboards.delete("your-id") +``` + +```typescript TypeScript +const result = await client.dashboards.delete("your-id"); +``` + + + + + +```python Python +client.dashboards.delete( + id: str, + *, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.dashboards.delete(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `id`. + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### dashboards.filter_values + +List the distinct values of a metric or attribute for use in dashboard filters. + + + +**MCP tool**: `get_dashboard_filter_values` + + + +```python Python +result = client.dashboards.filter_values() +``` + +```typescript TypeScript +const result = await client.dashboards.filterValues(); +``` + + + + + +```python Python +client.dashboards.filter_values( + *, + property_id: str | None | NotGiven = NOT_GIVEN, + metric_name: str | None | NotGiven = NOT_GIVEN, + metric_type: Literal['system_metric', 'eval_metric', 'annotation_metric', 'custom_attribute', 'custom_column'] | None | NotGiven = NOT_GIVEN, + source: Literal['traces', 'spans', 'sessions', 'users', 'voice_calls', 'prompts', 'datasets', 'dataset_column', 'simulation', 'both', 'all'] | None | NotGiven = NOT_GIVEN, + project_ids: str | None | NotGiven = NOT_GIVEN, + dataset_id: str | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + cursor: str | None | NotGiven = NOT_GIVEN, + attribute_type: Literal['string', 'number', 'boolean', 'array', 'map', 'json'] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardFilterValuesResult +``` + +```typescript TypeScript +client.dashboards.filterValues(params: DashboardsFilterValuesParams = {}, options?: RequestOptions): Promise + +export interface DashboardsFilterValuesParams { + /** Stable namespaced property identity returned by the metrics catalog. Legacy metric_name/metric_type remain accepted during migration. */ + property_id?: string | null; + metric_name?: string | null; + metric_type?: "system_metric" | "eval_metric" | "annotation_metric" | "custom_attribute" | "custom_column" | null; + source?: "traces" | "spans" | "sessions" | "users" | "voice_calls" | "prompts" | "datasets" | "dataset_column" | "simulation" | "both" | "all" | null; + project_ids?: string | null; + dataset_id?: string | null; + search?: string | null; + page_size?: number | null; + cursor?: string | null; + attribute_type?: "string" | "number" | "boolean" | "array" | "map" | "json" | null; +} +``` + + + +#### Parameters + + + Stable namespaced property identity returned by the metrics catalog. Legacy metric_name/metric_type remain accepted during migration. + + + + + + + + + + + +#### Returns + +[`DashboardFilterValuesResult`](/docs/sdk/reference/observability-models#dashboardfiltervaluesresult). + +### dashboards.get + +Return a dashboard and its widgets by identifier. + + + +**MCP tool**: `get_dashboard` + + + +```python Python +result = client.dashboards.get("your-id") +``` + +```typescript TypeScript +const result = await client.dashboards.get("your-id"); +``` + + + + + +```python Python +client.dashboards.get( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardDetail +``` + +```typescript TypeScript +client.dashboards.get(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `id`. + + +#### Returns + +[`DashboardDetail`](/docs/sdk/reference/observability-models#dashboarddetail). + +### dashboards.list + +List dashboards in the current workspace with their widget counts. + + + +**MCP tool**: `list_dashboards` + + + +```python Python +result = client.dashboards.list() +``` + +```typescript TypeScript +const result = await client.dashboards.list(); +``` + + + + + +```python Python +client.dashboards.list( + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> List[models.Dashboard] +``` + +```typescript TypeScript +client.dashboards.list(options?: RequestOptions): Promise> +``` + + + +#### Parameters + +This method takes no parameters beyond the per-call `options`. + +#### Returns + +A list of [`Dashboard`](/docs/sdk/reference/observability-models#dashboard). + +### dashboards.query + +Run an ad-hoc dashboard query (time_range and metrics, with optional filters and breakdowns) and return chart data without saving a widget. + + + +**MCP tool**: `query_dashboard_metrics` + + + +```python Python +result = client.dashboards.query(time_range="your-time-range", metrics=[]) +``` + +```typescript TypeScript +const result = await client.dashboards.query({ + time_range: "your-time-range", + metrics: [], +}); +``` + + + + + +```python Python +client.dashboards.query( + *, + time_range: dict[str, Any], + metrics: list[dict[str, Any]], + workflow: Literal['observability', 'dataset', 'simulation'] | None | NotGiven = NOT_GIVEN, + project_ids: list[str] | None | NotGiven = NOT_GIVEN, + granularity: Literal['minute', 'hour', 'day', 'week', 'month'] | None | NotGiven = NOT_GIVEN, + filters: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + breakdowns: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + allow_sampled: bool | None | NotGiven = NOT_GIVEN, + refresh: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardQueryResult +``` + +```typescript TypeScript +client.dashboards.query(params: DashboardsQueryParams, options?: RequestOptions): Promise + +export interface DashboardsQueryParams { + time_range: Record; + metrics: Array>; + workflow?: "observability" | "dataset" | "simulation" | null; + project_ids?: Array | null; + granularity?: "minute" | "hour" | "day" | "week" | "month" | null; + filters?: Array> | null; + breakdowns?: Array> | null; + allow_sampled?: boolean | null; + refresh?: boolean | null; +} +``` + + + +#### Parameters + + + + + + + + + + + +#### Returns + +[`DashboardQueryResult`](/docs/sdk/reference/observability-models#dashboardqueryresult). + +### dashboards.update + +Update the name and/or description of an existing dashboard (a partial update). + + + +**MCP tool**: `update_dashboard` + + + +```python Python +result = client.dashboards.update("your-id") +``` + +```typescript TypeScript +const result = await client.dashboards.update("your-id"); +``` + + + + + +```python Python +client.dashboards.update( + id: str, + *, + name: str | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardDetail +``` + +```typescript TypeScript +client.dashboards.update(id: string, params: DashboardsUpdateParams = {}, options?: RequestOptions): Promise + +export interface DashboardsUpdateParams { + name?: string | null; + description?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `id`. + + + + +#### Returns + +[`DashboardDetail`](/docs/sdk/reference/observability-models#dashboarddetail). + +## client.dashboards.metrics + +TypeScript: `client.dashboards.metrics`. + +### dashboards.metrics.list + +List the metrics available to dashboard queries across traces, datasets, and simulations. + + + +**MCP tool**: `list_dashboard_metrics` + + + +```python Python +result = client.dashboards.metrics.list() +``` + +```typescript TypeScript +const result = await client.dashboards.metrics.list(); +``` + + + + + +```python Python +client.dashboards.metrics.list( + *, + workflow: Literal['observability', 'dataset', 'simulation'] | None | NotGiven = NOT_GIVEN, + project_ids: str | None | NotGiven = NOT_GIVEN, + agent_definition_id: str | None | NotGiven = NOT_GIVEN, + per_eval_config: bool | None | NotGiven = NOT_GIVEN, + exclude_custom_attributes: bool | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + category: Literal['system_metric', 'eval_metric', 'annotation_metric', 'custom_attribute', 'custom_column'] | None | NotGiven = NOT_GIVEN, + role: Literal['metric', 'dimension'] | None | NotGiven = NOT_GIVEN, + source: Literal['traces', 'spans', 'sessions', 'users', 'voice_calls', 'prompts', 'datasets', 'simulation', 'both', 'all'] | None | NotGiven = NOT_GIVEN, + page: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + cursor_mode: bool | None | NotGiven = NOT_GIVEN, + cursor: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardMetricsCatalogResult +``` + +```typescript TypeScript +client.dashboards.metrics.list(params: DashboardsMetricsListParams = {}, options?: RequestOptions): Promise + +export interface DashboardsMetricsListParams { + workflow?: "observability" | "dataset" | "simulation" | null; + project_ids?: string | null; + agent_definition_id?: string | null; + per_eval_config?: boolean | null; + exclude_custom_attributes?: boolean | null; + search?: string | null; + category?: "system_metric" | "eval_metric" | "annotation_metric" | "custom_attribute" | "custom_column" | null; + role?: "metric" | "dimension" | null; + source?: "traces" | "spans" | "sessions" | "users" | "voice_calls" | "prompts" | "datasets" | "simulation" | "both" | "all" | null; + page?: number | null; + page_size?: number | null; + cursor_mode?: boolean | null; + cursor?: string | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + + + + +#### Returns + +[`DashboardMetricsCatalogResult`](/docs/sdk/reference/observability-models#dashboardmetricscatalogresult). + +## client.dashboards.widgets + +TypeScript: `client.dashboards.widgets`. + +### dashboards.widgets.create + +Add a widget to a dashboard. query_config uses the query_dashboard_metrics request shape (time_range plus metrics); discover metric names with list_dashboard_metrics. + + + +**MCP tool**: `create_dashboard_widget` + + + +```python Python +result = client.dashboards.widgets.create("your-dashboard-pk") +``` + +```typescript TypeScript +const result = await client.dashboards.widgets.create("your-dashboard-pk"); +``` + + + + + +```python Python +client.dashboards.widgets.create( + dashboard_pk: str, + *, + name: str | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + position: int | None | NotGiven = NOT_GIVEN, + width: int | None | NotGiven = NOT_GIVEN, + height: int | None | NotGiven = NOT_GIVEN, + query_config: dict[str, Any] | None | NotGiven = NOT_GIVEN, + chart_config: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardWidget +``` + +```typescript TypeScript +client.dashboards.widgets.create(dashboardPk: string, params: DashboardsWidgetsCreateParams = {}, options?: RequestOptions): Promise + +export interface DashboardsWidgetsCreateParams { + name?: string | null; + description?: string | null; + position?: number | null; + width?: number | null; + height?: number | null; + query_config?: Record | null; + chart_config?: Record | null; +} +``` + + + +#### Parameters + + + Positional argument `dashboard_pk`. + + + + + + + + + +#### Returns + +[`DashboardWidget`](/docs/sdk/reference/observability-models#dashboardwidget). + +### dashboards.widgets.get + +Return a dashboard widget, including its query_config and chart_config. + + + +**MCP tool**: `get_dashboard_widget` + + + +```python Python +result = client.dashboards.widgets.get("your-dashboard-pk", "your-id") +``` + +```typescript TypeScript +const result = await client.dashboards.widgets.get("your-dashboard-pk", "your-id"); +``` + + + + + +```python Python +client.dashboards.widgets.get( + dashboard_pk: str, + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardWidget +``` + +```typescript TypeScript +client.dashboards.widgets.get(dashboardPk: string, id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `dashboard_pk`. + + + Positional argument `id`. + + +#### Returns + +[`DashboardWidget`](/docs/sdk/reference/observability-models#dashboardwidget). + +### dashboards.widgets.list + +List the widgets on a dashboard. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_dashboard_widgets` + + + +```python Python +for item in client.dashboards.widgets.list("your-dashboard-pk"): + print(item) +``` + +```typescript TypeScript +for await (const item of client.dashboards.widgets.list("your-dashboard-pk")) { + console.log(item); +} +``` + + + + + +```python Python +client.dashboards.widgets.list( + dashboard_pk: str, + *, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.DashboardWidget] +``` + +```typescript TypeScript +client.dashboards.widgets.list(dashboardPk: string, params: DashboardsWidgetsListParams = {}, options?: RequestOptions): Pager + +export interface DashboardsWidgetsListParams { + /** Number of results to return per page. */ + limit?: number | null; +} +``` + + + +#### Parameters + + + Positional argument `dashboard_pk`. + + + Number of results to return per page. + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`DashboardWidget`](/docs/sdk/reference/observability-models#dashboardwidget) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### dashboards.widgets.query + +Execute a saved widget's query and return its chart data. + + + +**MCP tool**: `query_dashboard_widget` + + + +```python Python +result = client.dashboards.widgets.query("your-dashboard-pk", "your-id") +``` + +```typescript TypeScript +const result = await client.dashboards.widgets.query("your-dashboard-pk", "your-id"); +``` + + + + + +```python Python +client.dashboards.widgets.query( + dashboard_pk: str, + id: str, + *, + allow_sampled: bool | None | NotGiven = NOT_GIVEN, + refresh: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardQueryResult +``` + +```typescript TypeScript +client.dashboards.widgets.query(dashboardPk: string, id: string, params: DashboardsWidgetsQueryParams = {}, options?: RequestOptions): Promise + +export interface DashboardsWidgetsQueryParams { + allow_sampled?: boolean | null; + refresh?: boolean | null; +} +``` + + + +#### Parameters + + + Positional argument `dashboard_pk`. + + + Positional argument `id`. + + + + +#### Returns + +[`DashboardQueryResult`](/docs/sdk/reference/observability-models#dashboardqueryresult). + +### dashboards.widgets.update + +Update selected fields on a dashboard widget, such as its query_config, chart_config, or layout. + + + +**MCP tool**: `update_dashboard_widget` + + + +```python Python +result = client.dashboards.widgets.update("your-dashboard-pk", "your-id") +``` + +```typescript TypeScript +const result = await client.dashboards.widgets.update("your-dashboard-pk", "your-id"); +``` + + + + + +```python Python +client.dashboards.widgets.update( + dashboard_pk: str, + id: str, + *, + name: str | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + position: int | None | NotGiven = NOT_GIVEN, + width: int | None | NotGiven = NOT_GIVEN, + height: int | None | NotGiven = NOT_GIVEN, + query_config: dict[str, Any] | None | NotGiven = NOT_GIVEN, + chart_config: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardWidget +``` + +```typescript TypeScript +client.dashboards.widgets.update(dashboardPk: string, id: string, params: DashboardsWidgetsUpdateParams = {}, options?: RequestOptions): Promise + +export interface DashboardsWidgetsUpdateParams { + name?: string | null; + description?: string | null; + position?: number | null; + width?: number | null; + height?: number | null; + query_config?: Record | null; + chart_config?: Record | null; +} +``` + + + +#### Parameters + + + Positional argument `dashboard_pk`. + + + Positional argument `id`. + + + + + + + + + +#### Returns + +[`DashboardWidget`](/docs/sdk/reference/observability-models#dashboardwidget). diff --git a/src/pages/docs/sdk/reference/datasets-evals-models.mdx b/src/pages/docs/sdk/reference/datasets-evals-models.mdx new file mode 100644 index 000000000..2f3fce903 --- /dev/null +++ b/src/pages/docs/sdk/reference/datasets-evals-models.mdx @@ -0,0 +1,53 @@ +--- +title: "Datasets & evals response models" +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." +--- + +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)). + +## Models + +| Model | Fields | +|---|---| +| `Column` | `id: string`, `name: string`, `data_type: string`, `dataset: string`, `source: string`, `source_id: string` | +| `CustomEvalConfig` | `id: string`, `eval_template: string`, `name: string`, `config: any`, `mapping: any`, `project: string`, `filters: any`, `error_localizer: boolean`, `kb_id: string`, `model: string`, `eval_group: any` | +| `DatasetColumnsMutationResult` | `message: string`, `data:` [`Column`](#column)[] | +| `DatasetCreateStartedResult` | `message: string`, `dataset_id: string`, `dataset_name: string`, `dataset_model_type: string` | +| `DatasetEvalStatsItem` | `id: string`, `name: string`, `output_type: string`, `result:` [`DatasetEvalStatsMetric`](#datasetevalstatsmetric)[], `total_pass_rate: number`, `total_avg: any`, `total_choices_avg: any`, `is_numeric_eval: boolean`, `is_numeric_eval_percentage: boolean` | +| `DatasetEvalStatsMetric` | `id: string`, `name: string`, `total_cells: integer`, `output: any` | +| `DatasetListItem` | `id: string`, `name: string`, `number_of_datapoints: integer`, `number_of_experiments: integer`, `number_of_optimisations: integer`, `derived_datasets: integer`, `created_at: string`, `dataset_type: string` | +| `DatasetNameItem` | `dataset_id: string`, `name: string`, `model_type: string` | +| `DatasetNamesResult` | `datasets:` [`DatasetNameItem`](#datasetnameitem)[] | +| `DatasetOptimizationColumnConfigItem` | `id: string`, `name: string`, `is_visible: boolean` | +| `DatasetOptimizationDetail` | `optimiser_name: string`, `optimiser_type: string`, `model: string`, `model_deprecated: boolean`, `provider_logo: string`, `configuration: any`, `status: string`, `error_message: string`, `start_time: string`, `parameters:` [`DatasetOptimizationParameterItem`](#datasetoptimizationparameteritem)[], `column_id: string`, `column_name: string`, `best_score: number`, `baseline_score: number`, `table:` [`DatasetOptimizationTrialTableRow`](#datasetoptimizationtrialtablerow)[], `column_config:` [`DatasetOptimizationColumnConfigItem`](#datasetoptimizationcolumnconfigitem)[], `optimizer_model_id: string`, `user_eval_templates:` [`DatasetOptimizationEvalTemplateItem`](#datasetoptimizationevaltemplateitem)[] | +| `DatasetOptimizationEvalTemplateItem` | `id: string`, `eval_id: string`, `name: string`, `template_id: string` | +| `DatasetOptimizationParameterItem` | `key: string`, `label: string`, `description: string`, `value: any` | +| `DatasetOptimizationTrialEvalScore` | `score: number`, `percentage_change: number` | +| `DatasetOptimizationTrialTableRow` | `id: string`, `trial: string`, `prompt: string`, `is_best: boolean`, `score_percentage_change: number`, `eval_scores: any` | +| `DatasetRunPromptStatsPrompt` | `id: string`, `name: string`, `input_token: number`, `output_token: number`, `total_token: number` | +| `DatasetRunPromptStatsResult` | `avg_tokens: number`, `avg_cost: number`, `avg_time: number`, `prompts:` [`DatasetRunPromptStatsPrompt`](#datasetrunpromptstatsprompt)[] | +| `DatasetTableColumn` | `id: string`, `name: string`, `data_type: string`, `is_visible: boolean`, `is_frozen: boolean`, `source_type: string`, `origin_type: string`, `source_id: string`, `order_index: integer`, `status: string`, `average_score: number`, `reason_column: boolean`, `is_numeric_eval: boolean`, `is_numeric_eval_percentage: boolean`, `eval_tag: string[]`, `metadata: any`, `choices_map: any` | +| `DatasetTableMetadata` | `dataset_name: string`, `experiment_id: string`, `experiment_name: string`, `total_rows: integer`, `total_pages: integer`, `page_size: integer`, `current_page_index: integer`, `has_more: boolean`, `next_page_index: integer`, `next_cursor: string`, `is_exact: boolean`, `snapshot_bound: boolean`, `error_messages: string[]`, `status: any` | +| `DatasetTableResult` | `metadata:` [`DatasetTableMetadata`](#datasettablemetadata), `column_config:` [`DatasetTableColumn`](#datasettablecolumn)[], `table:` [`DatasetTableRow`](#datasettablerow)[], `dataset_config: any`, `synthetic_dataset: boolean`, `synthetic_dataset_percentage: number`, `synthetic_regenerate: boolean`, `is_processing_data: boolean` | +| `DatasetTableRow` | `row_id: string` | +| `EvalExecutionResponseResult` | `output: any`, `result: any`, `reason: string`, `score: any`, `metadata: any`, `log_id: string`, `error_localizer: any`, `error_details: any` | +| `EvalGroup` | `id: string`, `name: string`, `organization: string`, `workspace: string`, `created_at: string`, `updated_at: string`, `description: string`, `created_by: any`, `is_sample: boolean` | +| `EvalListResult` | `evals: any[]`, `eval_recommendations: string[]` | +| `EvalTask` | `id: string`, `project: string`, `name: string`, `filters: object`, `sampling_rate: number`, `last_run: string`, `spans_limit: integer`, `run_type: string`, `row_type: string`, `status: string`, `start_time: string`, `end_time: string`, `created_at: string`, `updated_at: string`, `evals_details: any`, `evals: string[]`, `failed_spans: any`, `progress: any` | +| `EvalTaskCreateResult` | `id: string` | +| `EvalTaskMessageResult` | `message: string` | +| `EvalTaskUpdateResult` | `message: string`, `edit_type: string`, `task_id: string` | +| `EvalTemplateChartPoint` | `timestamp: string`, `value: number` | +| `EvalTemplateCreateResponseResult` | `id: string`, `name: string`, `version: string` | +| `EvalTemplateDetailResponseResult` | `id: string`, `name: string`, `description: string`, `template_type: string`, `eval_type: string`, `instructions: string`, `model: string`, `output_type: string`, `pass_threshold: number`, `choice_scores: any`, `choices: any`, `multi_choice: boolean`, `code: string`, `code_language: string`, `required_keys: string[]`, `owner: string`, `created_by_name: string`, `version_count: integer`, `current_version: string`, `tags: string[]`, `check_internet: boolean`, `error_localizer_enabled: boolean`, `template_format: string`, `aggregation_enabled: boolean`, `aggregation_function: string`, `composite_child_axis: string`, `config: any`, `created_at: string`, `updated_at: string` | +| `EvalTemplateListItem` | `id: string`, `name: string`, `template_type: string`, `eval_type: string`, `output_type: string`, `owner: string`, `created_by_name: string`, `version_count: integer`, `current_version: string`, `last_updated: string`, `thirty_day_chart:` [`EvalTemplateChartPoint`](#evaltemplatechartpoint)[], `thirty_day_error_rate:` [`EvalTemplateChartPoint`](#evaltemplatechartpoint)[], `thirty_day_run_count: integer`, `tags: string[]` | +| `EvalTemplateListResponseResult` | `items:` [`EvalTemplateListItem`](#evaltemplatelistitem)[], `total: integer`, `page: integer`, `page_size: integer` | +| `EvalTemplateUpdateResponseResult` | `id: string`, `name: string`, `updated: boolean` | +| `EvalsConfigsCreateResult` | `id: string` | +| `ExperimentDetailV2` | `id: string`, `name: string`, `dataset_id: string`, `column_id: string`, `experiment_type: string`, `status: string`, `snapshot_dataset_id: string`, `prompt_configs: any`, `agent_configs: any`, `user_eval_metrics: any`, `created_at: string` | +| `ExperimentListV2` | `id: string`, `name: string`, `status: string`, `experiment_type: string`, `eval_templates_count: any`, `created_at: string`, `models_count: any`, `agents_count: any`, `dataset: string` | +| `LocalFileDatasetCreateStartedResult` | `message: string`, `dataset_id: string`, `dataset_name: string`, `dataset_model_type: string`, `processing_status: string`, `estimated_rows: integer`, `estimated_columns: integer` | +| `ModelHubSuccessMessageResult` | `success: string` | +| `OptimizationsCreateResult` | `id: string`, `name: string`, `optimizer_algorithm: string`, `optimizer_config: any`, `created_at: string` | +| `_EvalTaskListResultResponse` | `metadata: any`, `table:` [`_EvalTaskListRowResponse`](#_evaltasklistrowresponse)[], `config: any[]` | +| `_EvalTaskListRowResponse` | `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` | diff --git a/src/pages/docs/sdk/reference/datasets.mdx b/src/pages/docs/sdk/reference/datasets.mdx new file mode 100644 index 000000000..981d201ed --- /dev/null +++ b/src/pages/docs/sdk/reference/datasets.mdx @@ -0,0 +1,1279 @@ +--- +title: "Datasets" +description: "Reference for client.datasets in the Future AGI Python and TypeScript SDKs: datasets.create, datasets.create_from_file, datasets.create_from_huggingface, datasets.delete, datasets.get, datasets.list and 14 more." +--- + +`client.datasets` on `fi.Client` (Python) and `client.datasets` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.datasets.cells`, `client.datasets.columns`, `client.datasets.evals`, `client.datasets.prompts`, `client.datasets.rows`. The models these methods return are on [Datasets & evals response models](/docs/sdk/reference/datasets-evals-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`datasets.create`](#datasetscreate) | Create an empty dataset in the current workspace. | +| [`datasets.create_from_file`](#datasetscreate_from_file) | Create a dataset by uploading a local CSV, JSON, JSONL or Excel file. | +| [`datasets.create_from_huggingface`](#datasetscreate_from_huggingface) | Create a dataset from a Hugging Face dataset split. | +| [`datasets.delete`](#datasetsdelete) | Soft-delete one or more datasets by passing dataset_ids. | +| [`datasets.get`](#datasetsget) | Return the rows, columns, and metadata for a dataset. | +| [`datasets.list`](#datasetslist) | List datasets available in the current workspace. | +| [`datasets.list_names`](#datasetslist_names) | Return the id and name of every dataset in the workspace, without paging. | +| [`datasets.cells.update`](#datasetscellsupdate) | Set the value of a single dataset cell. | +| [`datasets.columns.add`](#datasetscolumnsadd) | Add columns to a dataset. | +| [`datasets.columns.add_static`](#datasetscolumnsadd_static) | Create a named static input column before adding dataset rows. | +| [`datasets.columns.rename`](#datasetscolumnsrename) | Rename an existing dataset column. | +| [`datasets.evals.add`](#datasetsevalsadd) | Attach an evaluation template to a dataset with a lowercase name (letters, digits, hyphens or underscores; no spaces) and config.mapping column mappings. | +| [`datasets.evals.list`](#datasetsevalslist) | List evaluations attached to a dataset by supplying eval_type=user, including their IDs, configuration and status. | +| [`datasets.evals.run`](#datasetsevalsrun) | Start the configured evaluations for a dataset. | +| [`datasets.evals.stats`](#datasetsevalsstats) | Per-evaluation score statistics for a dataset. | +| [`datasets.prompts.add`](#datasetspromptsadd) | Create a dataset prompt output column and immediately schedule processing of dataset rows. | +| [`datasets.prompts.run`](#datasetspromptsrun) | Queue configured dataset prompts by run_prompt_ids. | +| [`datasets.prompts.stats`](#datasetspromptsstats) | Return dataset prompt IDs and token, cost and timing statistics. | +| [`datasets.prompts.update`](#datasetspromptsupdate) | Update a dataset prompt column using dataset_id, column_id and config. | +| [`datasets.rows.add`](#datasetsrowsadd) | Add rows to an existing dataset using cells with column_name and value. | + +## client.datasets + +### datasets.create + +Create an empty dataset in the current workspace. Use create_dataset_column before add_dataset_rows. + + + +**MCP tool**: `create_dataset` + + + +```python Python +result = client.datasets.create(new_dataset_name="your-new-dataset-name") +``` + +```typescript TypeScript +const result = await client.datasets.create({ new_dataset_name: "your-new-dataset-name" }); +``` + + + + + +```python Python +client.datasets.create( + *, + new_dataset_name: str, + model_type: str | None | NotGiven = NOT_GIVEN, + is_sdk: bool | None | NotGiven = NOT_GIVEN, + row: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DatasetCreateStartedResult +``` + +```typescript TypeScript +client.datasets.create(params: DatasetsCreateParams, options?: RequestOptions): Promise + +export interface DatasetsCreateParams { + new_dataset_name: string; + model_type?: string | null; + is_sdk?: boolean | null; + row?: number | null; +} +``` + + + +#### Parameters + + + + + + +#### Returns + +[`DatasetCreateStartedResult`](/docs/sdk/reference/datasets-evals-models#datasetcreatestartedresult). + +### datasets.create_from_file + +Create a dataset by uploading a local CSV, JSON, JSONL or Excel file. Processing is asynchronous; read datasets.get for the result. + + + +**Multipart upload**: file parameters take a path, bytes or an open file + + + +```python Python +result = client.datasets.create_from_file( + file="path/to/file", + new_dataset_name="your-new-dataset-name", + model_type="your-model-type", +) +``` + +```typescript TypeScript +const result = await client.datasets.createFromFile({ + file: "path/to/file", + new_dataset_name: "your-new-dataset-name", + model_type: "your-model-type", +}); +``` + + + + + +```python Python +client.datasets.create_from_file( + *, + file: FileInput, + new_dataset_name: str, + model_type: str, + source: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.LocalFileDatasetCreateStartedResult +``` + +```typescript TypeScript +client.datasets.createFromFile(params: DatasetsCreateFromFileParams, options?: RequestOptions): Promise + +export interface DatasetsCreateFromFileParams { + file: FileInput; + new_dataset_name: string; + model_type: string; + source?: string | null; +} +``` + + + +#### Parameters + + + + + + +#### Returns + +[`LocalFileDatasetCreateStartedResult`](/docs/sdk/reference/datasets-evals-models#localfiledatasetcreatestartedresult). + +### datasets.create_from_huggingface + +Create a dataset from a Hugging Face dataset split. + + + + + +```python Python +result = client.datasets.create_from_huggingface(huggingface_dataset_name="your-huggingface-dataset-name", huggingface_dataset_split="your-huggingface-dataset-split") +``` + +```typescript TypeScript +const result = await client.datasets.createFromHuggingface({ + huggingface_dataset_name: "your-huggingface-dataset-name", + huggingface_dataset_split: "your-huggingface-dataset-split", +}); +``` + + + + + +```python Python +client.datasets.create_from_huggingface( + *, + huggingface_dataset_name: str, + huggingface_dataset_split: str, + name: str | None | NotGiven = NOT_GIVEN, + model_type: str | None | NotGiven = NOT_GIVEN, + num_rows: int | None | NotGiven = NOT_GIVEN, + huggingface_dataset_config: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DatasetCreateStartedResult +``` + +```typescript TypeScript +client.datasets.createFromHuggingface(params: DatasetsCreateFromHuggingfaceParams, options?: RequestOptions): Promise + +export interface DatasetsCreateFromHuggingfaceParams { + huggingface_dataset_name: string; + huggingface_dataset_split: string; + name?: string | null; + model_type?: string | null; + num_rows?: number | null; + huggingface_dataset_config?: string | null; +} +``` + + + +#### Parameters + + + + + + + + +#### Returns + +[`DatasetCreateStartedResult`](/docs/sdk/reference/datasets-evals-models#datasetcreatestartedresult). + +### datasets.delete + +Soft-delete one or more datasets by passing dataset_ids. This is the only way to remove a dataset created earlier; deletion cascades to the dataset's rows, columns and attached evaluations. + + + +**MCP tool**: `delete_datasets` + + + +```python Python +result = client.datasets.delete(dataset_ids=[]) +``` + +```typescript TypeScript +const result = await client.datasets.delete({ dataset_ids: [] }); +``` + + + + + +```python Python +client.datasets.delete( + *, + dataset_ids: list[str], + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.datasets.delete(params: DatasetsDeleteParams, options?: RequestOptions): Promise + +export interface DatasetsDeleteParams { + dataset_ids: Array; +} +``` + + + +#### Parameters + + + +#### Returns + +`string`. + +### datasets.get + +Return the rows, columns, and metadata for a dataset. + + + +**MCP tool**: `get_dataset` + + + +```python Python +result = client.datasets.get("your-dataset-id") +``` + +```typescript TypeScript +const result = await client.datasets.get("your-dataset-id"); +``` + + + + + +```python Python +client.datasets.get( + dataset_id: str, + *, + filters: str | None | NotGiven = NOT_GIVEN, + sort: str | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + current_page_index: int | None | NotGiven = NOT_GIVEN, + column_config_only: bool | None | NotGiven = NOT_GIVEN, + exact_snapshot: bool | None | NotGiven = NOT_GIVEN, + cursor: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DatasetTableResult +``` + +```typescript TypeScript +client.datasets.get(datasetId: string, params: DatasetsGetParams = {}, options?: RequestOptions): Promise + +export interface DatasetsGetParams { + filters?: string | null; + sort?: string | null; + search?: string | null; + page_size?: number | null; + current_page_index?: number | null; + column_config_only?: boolean | null; + /** Start an exact MVCC-bound dataset read. Exact reads start at page 0 and return a signed next_cursor when more rows remain. */ + exact_snapshot?: boolean | null; + /** Signed next_cursor from the preceding exact dataset page. Keep the same page_size and current_page_index sequence. */ + cursor?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + + + + + + + + Start an exact MVCC-bound dataset read. Exact reads start at page 0 and return a signed next_cursor when more rows remain. + + + Signed next_cursor from the preceding exact dataset page. Keep the same page_size and current_page_index sequence. + + +#### Returns + +[`DatasetTableResult`](/docs/sdk/reference/datasets-evals-models#datasettableresult). + +### datasets.list + +List datasets available in the current workspace. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_datasets` + + + +```python Python +for item in client.datasets.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.datasets.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.datasets.list( + *, + search_text: str | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + sort: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.DatasetListItem] +``` + +```typescript TypeScript +client.datasets.list(params: DatasetsListParams = {}, options?: RequestOptions): Pager + +export interface DatasetsListParams { + search_text?: string | null; + page_size?: number | null; + sort?: string | null; +} +``` + + + +#### Parameters + + + + + +The pager sends `page` itself; pass `page_size` to change the page size. + +#### Returns + +A pager of [`DatasetListItem`](/docs/sdk/reference/datasets-evals-models#datasetlistitem) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### datasets.list_names + +Return the id and name of every dataset in the workspace, without paging. + + + + + +```python Python +result = client.datasets.list_names() +``` + +```typescript TypeScript +const result = await client.datasets.listNames(); +``` + + + + + +```python Python +client.datasets.list_names( + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DatasetNamesResult +``` + +```typescript TypeScript +client.datasets.listNames(options?: RequestOptions): Promise +``` + + + +#### Parameters + +This method takes no parameters beyond the per-call `options`. + +#### Returns + +[`DatasetNamesResult`](/docs/sdk/reference/datasets-evals-models#datasetnamesresult). + +## client.datasets.cells + +TypeScript: `client.datasets.cells`. + +### datasets.cells.update + +Set the value of a single dataset cell. Use this to correct one value; add_dataset_rows only appends and cannot edit an existing row. + + + +**MCP tool**: `update_dataset_cell` + + + +```python Python +result = client.datasets.cells.update( + "your-dataset-id", + row_id="your-row-id", + column_id="your-column-id", +) +``` + +```typescript TypeScript +const result = await client.datasets.cells.update("your-dataset-id", { + row_id: "your-row-id", + column_id: "your-column-id", +}); +``` + + + + + +```python Python +client.datasets.cells.update( + dataset_id: str, + *, + row_id: str, + column_id: str, + new_value: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.datasets.cells.update(datasetId: string, params: DatasetsCellsUpdateParams, options?: RequestOptions): Promise + +export interface DatasetsCellsUpdateParams { + row_id: string; + column_id: string; + new_value?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + + + + +#### Returns + +`string`. + +## client.datasets.columns + +TypeScript: `client.datasets.columns`. + +### datasets.columns.add + +Add columns to a dataset. + + + + + +```python Python +result = client.datasets.columns.add("your-dataset-id", new_columns_data=[]) +``` + +```typescript TypeScript +const result = await client.datasets.columns.add("your-dataset-id", { new_columns_data: [] }); +``` + + + + + +```python Python +client.datasets.columns.add( + dataset_id: str, + *, + new_columns_data: list[dict[str, Any]], + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DatasetColumnsMutationResult +``` + +```typescript TypeScript +client.datasets.columns.add(datasetId: string, params: DatasetsColumnsAddParams, options?: RequestOptions): Promise + +export interface DatasetsColumnsAddParams { + new_columns_data: Array>; +} +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + + +#### Returns + +[`DatasetColumnsMutationResult`](/docs/sdk/reference/datasets-evals-models#datasetcolumnsmutationresult). + +### datasets.columns.add_static + +Create a named static input column before adding dataset rows. Supply column_type using the API schema. + + + +**MCP tool**: `create_dataset_column` + + + +```python Python +result = client.datasets.columns.add_static( + "your-dataset-id", + new_column_name="your-new-column-name", + column_type="your-column-type", +) +``` + +```typescript TypeScript +const result = await client.datasets.columns.addStatic("your-dataset-id", { + new_column_name: "your-new-column-name", + column_type: "your-column-type", +}); +``` + + + + + +```python Python +client.datasets.columns.add_static( + dataset_id: str, + *, + new_column_name: str, + column_type: str, + source: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.datasets.columns.addStatic(datasetId: string, params: DatasetsColumnsAddStaticParams, options?: RequestOptions): Promise + +export interface DatasetsColumnsAddStaticParams { + new_column_name: string; + column_type: string; + source?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + + + + +#### Returns + +`string`. + +### datasets.columns.rename + +Rename an existing dataset column. This does not change its type or cell values. + + + +**MCP tool**: `rename_dataset_column` + + + +```python Python +result = client.datasets.columns.rename( + "your-dataset-id", + "your-column-id", + new_column_name="your-new-column-name", +) +``` + +```typescript TypeScript +const result = await client.datasets.columns.rename("your-dataset-id", "your-column-id", { new_column_name: "your-new-column-name" }); +``` + + + + + +```python Python +client.datasets.columns.rename( + dataset_id: str, + column_id: str, + *, + new_column_name: str, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.datasets.columns.rename(datasetId: string, columnId: string, params: DatasetsColumnsRenameParams, options?: RequestOptions): Promise + +export interface DatasetsColumnsRenameParams { + new_column_name: string; +} +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + + Positional argument `column_id`. + + + +#### Returns + +`string`. + +## client.datasets.evals + +TypeScript: `client.datasets.evals`. + +### datasets.evals.add + +Attach an evaluation template to a dataset with a lowercase name (letters, digits, hyphens or underscores; no spaces) and config.mapping column mappings. Set run=false for setup only; run=true marks it for processing. Use list_dataset_evaluations to discover the attached evaluation ID. + + + +**MCP tool**: `configure_dataset_evaluation` + + + +```python Python +result = client.datasets.evals.add( + "your-dataset-id", + name="your-name", + template_id="your-template-id", + config={}, +) +``` + +```typescript TypeScript +const result = await client.datasets.evals.add("your-dataset-id", { + name: "your-name", + template_id: "your-template-id", + config: {}, +}); +``` + + + + + +```python Python +client.datasets.evals.add( + dataset_id: str, + *, + name: str, + template_id: str, + config: dict[str, Any], + kb_id: str | None | NotGiven = NOT_GIVEN, + error_localizer: bool | None | NotGiven = NOT_GIVEN, + model: str | None | NotGiven = NOT_GIVEN, + eval_type: str | None | NotGiven = NOT_GIVEN, + run: bool | None | NotGiven = NOT_GIVEN, + save_as_template: bool | None | NotGiven = NOT_GIVEN, + experiment_id: str | None | NotGiven = NOT_GIVEN, + composite_weight_overrides: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.datasets.evals.add(datasetId: string, params: DatasetsEvalsAddParams, options?: RequestOptions): Promise + +export interface DatasetsEvalsAddParams { + name: string; + template_id: string; + config: Record; + kb_id?: string | null; + error_localizer?: boolean | null; + model?: string | null; + eval_type?: string | null; + run?: boolean | null; + save_as_template?: boolean | null; + experiment_id?: string | null; + composite_weight_overrides?: Record | null; +} +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + + + + + + + + + + + + +#### Returns + +`string`. + +### datasets.evals.list + +List evaluations attached to a dataset by supplying eval_type=user, including their IDs, configuration and status. These IDs, not template IDs, are used by run_dataset_evals. Without eval_type=user, the API lists available evaluation templates. + + + +**MCP tool**: `list_dataset_evaluations` + + + +```python Python +result = client.datasets.evals.list("your-dataset-id") +``` + +```typescript TypeScript +const result = await client.datasets.evals.list("your-dataset-id"); +``` + + + + + +```python Python +client.datasets.evals.list( + dataset_id: str, + *, + eval_type: str | None | NotGiven = NOT_GIVEN, + search_text: str | None | NotGiven = NOT_GIVEN, + eval_categories: str | None | NotGiven = NOT_GIVEN, + eval_tags: list[str] | None | NotGiven = NOT_GIVEN, + use_cases: list[str] | None | NotGiven = NOT_GIVEN, + experiment_id: str | None | NotGiven = NOT_GIVEN, + order: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalListResult +``` + +```typescript TypeScript +client.datasets.evals.list(datasetId: string, params: DatasetsEvalsListParams = {}, options?: RequestOptions): Promise + +export interface DatasetsEvalsListParams { + /** Use user to list evaluations attached to this dataset, including their runnable IDs. */ + eval_type?: string | null; + search_text?: string | null; + eval_categories?: string | null; + eval_tags?: Array | null; + use_cases?: Array | null; + experiment_id?: string | null; + order?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + + Use user to list evaluations attached to this dataset, including their runnable IDs. + + + + + + + + +#### Returns + +[`EvalListResult`](/docs/sdk/reference/datasets-evals-models#evallistresult). + +### datasets.evals.run + +Start the configured evaluations for a dataset. + + + +**MCP tool**: `run_dataset_evals` + + + +```python Python +result = client.datasets.evals.run("your-dataset-id", user_eval_ids=[]) +``` + +```typescript TypeScript +const result = await client.datasets.evals.run("your-dataset-id", { user_eval_ids: [] }); +``` + + + + + +```python Python +client.datasets.evals.run( + dataset_id: str, + *, + user_eval_ids: list[str], + experiment_id: str | None | NotGiven = NOT_GIVEN, + failed_only: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.datasets.evals.run(datasetId: string, params: DatasetsEvalsRunParams, options?: RequestOptions): Promise + +export interface DatasetsEvalsRunParams { + user_eval_ids: Array; + experiment_id?: string | null; + failed_only?: boolean | null; +} +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + + + + +#### Returns + +`string`. + +### datasets.evals.stats + +Per-evaluation score statistics for a dataset. + + + + + +```python Python +result = client.datasets.evals.stats("your-dataset-id") +``` + +```typescript TypeScript +const result = await client.datasets.evals.stats("your-dataset-id"); +``` + + + + + +```python Python +client.datasets.evals.stats( + dataset_id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> List[models.DatasetEvalStatsItem] +``` + +```typescript TypeScript +client.datasets.evals.stats(datasetId: string, options?: RequestOptions): Promise> +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + +#### Returns + +A list of [`DatasetEvalStatsItem`](/docs/sdk/reference/datasets-evals-models#datasetevalstatsitem). + +## client.datasets.prompts + +TypeScript: `client.datasets.prompts`. + +### datasets.prompts.add + +Create a dataset prompt output column and immediately schedule processing of dataset rows. This can incur model usage charges. Supply dataset_id, name and config; this is separate from workbench run_prompt. + + + +**MCP tool**: `add_dataset_prompt` + + + +```python Python +result = client.datasets.prompts.add(dataset_id="your-dataset-id", name="your-name") +``` + +```typescript TypeScript +const result = await client.datasets.prompts.add({ + dataset_id: "your-dataset-id", + name: "your-name", +}); +``` + + + + + +```python Python +client.datasets.prompts.add( + *, + dataset_id: str, + name: str, + config: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.datasets.prompts.add(params: DatasetsPromptsAddParams, options?: RequestOptions): Promise + +export interface DatasetsPromptsAddParams { + dataset_id: string; + name: string; + config?: Record | null; +} +``` + + + +#### Parameters + + + + + +#### Returns + +`string`. + +### datasets.prompts.run + +Queue configured dataset prompts by run_prompt_ids. Supply row_ids for selected rows, or selected_all_rows=true for all rows; with selected_all_rows=true, row_ids are EXCLUDED. Poll get_dataset for cell results and status. + + + +**MCP tool**: `run_dataset_prompts` + + + +```python Python +result = client.datasets.prompts.run(run_prompt_ids=[]) +``` + +```typescript TypeScript +const result = await client.datasets.prompts.run({ run_prompt_ids: [] }); +``` + + + + + +```python Python +client.datasets.prompts.run( + *, + run_prompt_ids: list[str], + row_ids: list[str] | None | NotGiven = NOT_GIVEN, + selected_all_rows: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.ModelHubSuccessMessageResult +``` + +```typescript TypeScript +client.datasets.prompts.run(params: DatasetsPromptsRunParams, options?: RequestOptions): Promise + +export interface DatasetsPromptsRunParams { + run_prompt_ids: Array; + row_ids?: Array | null; + selected_all_rows?: boolean | null; +} +``` + + + +#### Parameters + + + + + +#### Returns + +[`ModelHubSuccessMessageResult`](/docs/sdk/reference/datasets-evals-models#modelhubsuccessmessageresult). + +### datasets.prompts.stats + +Return dataset prompt IDs and token, cost and timing statistics. This is not execution status; use get_dataset for cell outputs and status. + + + +**MCP tool**: `get_dataset_prompt_stats` + + + +```python Python +result = client.datasets.prompts.stats("your-dataset-id") +``` + +```typescript TypeScript +const result = await client.datasets.prompts.stats("your-dataset-id"); +``` + + + + + +```python Python +client.datasets.prompts.stats( + dataset_id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DatasetRunPromptStatsResult +``` + +```typescript TypeScript +client.datasets.prompts.stats(datasetId: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + +#### Returns + +[`DatasetRunPromptStatsResult`](/docs/sdk/reference/datasets-evals-models#datasetrunpromptstatsresult). + +### datasets.prompts.update + +Update a dataset prompt column using dataset_id, column_id and config. This can schedule processing and incur model usage charges. + + + +**MCP tool**: `update_dataset_prompt` + + + +```python Python +result = client.datasets.prompts.update(dataset_id="your-dataset-id", column_id="your-column-id") +``` + +```typescript TypeScript +const result = await client.datasets.prompts.update({ + dataset_id: "your-dataset-id", + column_id: "your-column-id", +}); +``` + + + + + +```python Python +client.datasets.prompts.update( + *, + dataset_id: str, + column_id: str, + name: str | None | NotGiven = NOT_GIVEN, + config: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.datasets.prompts.update(params: DatasetsPromptsUpdateParams, options?: RequestOptions): Promise + +export interface DatasetsPromptsUpdateParams { + dataset_id: string; + column_id: string; + name?: string | null; + config?: Record | null; +} +``` + + + +#### Parameters + + + + + + +#### Returns + +`string`. + +## client.datasets.rows + +TypeScript: `client.datasets.rows`. + +### datasets.rows.add + +Add rows to an existing dataset using cells with column_name and value. Column names must already exist in the dataset. + + + +**MCP tool**: `add_dataset_rows` + + + **Beta.** This method may change without notice; calling it emits a one-time warning. + + + + +```python Python +result = client.datasets.rows.add("your-dataset-id", rows=[]) +``` + +```typescript TypeScript +const result = await client.datasets.rows.add("your-dataset-id", { rows: [] }); +``` + + + + + +```python Python +client.datasets.rows.add( + dataset_id: str, + *, + rows: list[dict[str, Any]], + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.datasets.rows.add(datasetId: string, params: DatasetsRowsAddParams, options?: RequestOptions): Promise + +export interface DatasetsRowsAddParams { + rows: Array>; +} +``` + + + +#### Parameters + + + Positional argument `dataset_id`. + + + +#### Returns + +`string`. diff --git a/src/pages/docs/sdk/reference/error-clusters.mdx b/src/pages/docs/sdk/reference/error-clusters.mdx new file mode 100644 index 000000000..61039f410 --- /dev/null +++ b/src/pages/docs/sdk/reference/error-clusters.mdx @@ -0,0 +1,150 @@ +--- +title: "Error clusters" +description: "Reference for client.error_clusters in the Future AGI Python and TypeScript SDKs: error_clusters.get, error_clusters.list." +--- + +`client.error_clusters` on `fi.Client` (Python) and `client.errorClusters` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Observability response models](/docs/sdk/reference/observability-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`error_clusters.get`](#error_clustersget) | Return an error issue and its grouped trace information. | +| [`error_clusters.list`](#error_clusterslist) | List grouped error issues detected in project traces. | + +## client.error_clusters + +### error_clusters.get + +Return an error issue and its grouped trace information. + + + +**MCP tool**: `get_error_cluster` + + + +```python Python +result = client.error_clusters.get("your-cluster-id") +``` + +```typescript TypeScript +const result = await client.errorClusters.get("your-cluster-id"); +``` + + + + + +```python Python +client.error_clusters.get( + cluster_id: str, + *, + project_id: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.FeedDetailCore +``` + +```typescript TypeScript +client.errorClusters.get(clusterId: string, params: ErrorClustersGetParams = {}, options?: RequestOptions): Promise + +export interface ErrorClustersGetParams { + project_id?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `cluster_id`. + + + +#### Returns + +[`FeedDetailCore`](/docs/sdk/reference/observability-models#feeddetailcore). + +### error_clusters.list + +List grouped error issues detected in project traces. + + + +**MCP tool**: `list_error_clusters` + + + +```python Python +result = client.error_clusters.list() +``` + +```typescript TypeScript +const result = await client.errorClusters.list(); +``` + + + + + +```python Python +client.error_clusters.list( + *, + project_id: str | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + status: Literal['escalating', 'for_review', 'acknowledged', 'resolved'] | None | NotGiven = NOT_GIVEN, + severity: Literal['critical', 'high', 'medium', 'low'] | None | NotGiven = NOT_GIVEN, + fix_layer: str | None | NotGiven = NOT_GIVEN, + source: Literal['scanner', 'eval'] | None | NotGiven = NOT_GIVEN, + issue_group: str | None | NotGiven = NOT_GIVEN, + time_range_days: int | None | NotGiven = NOT_GIVEN, + sort_by: Literal['last_seen', 'first_seen', 'error_count', 'unique_traces', 'severity'] | None | NotGiven = NOT_GIVEN, + sort_dir: Literal['asc', 'desc'] | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + offset: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.FeedListResponse +``` + +```typescript TypeScript +client.errorClusters.list(params: ErrorClustersListParams = {}, options?: RequestOptions): Promise + +export interface ErrorClustersListParams { + project_id?: string | null; + search?: string | null; + status?: "escalating" | "for_review" | "acknowledged" | "resolved" | null; + severity?: "critical" | "high" | "medium" | "low" | null; + fix_layer?: string | null; + source?: "scanner" | "eval" | null; + issue_group?: string | null; + time_range_days?: number | null; + sort_by?: "last_seen" | "first_seen" | "error_count" | "unique_traces" | "severity" | null; + sort_dir?: "asc" | "desc" | null; + limit?: number | null; + offset?: number | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + + + +#### Returns + +[`FeedListResponse`](/docs/sdk/reference/observability-models#feedlistresponse). diff --git a/src/pages/docs/sdk/reference/evals.mdx b/src/pages/docs/sdk/reference/evals.mdx new file mode 100644 index 000000000..3a2761deb --- /dev/null +++ b/src/pages/docs/sdk/reference/evals.mdx @@ -0,0 +1,1159 @@ +--- +title: "Evals" +description: "Reference for client.evals in the Future AGI Python and TypeScript SDKs: evals.test, evals.configs.create, evals.configs.list, evals.groups.get, evals.groups.list, evals.tasks.create and 9 more." +--- + +`client.evals` on `fi.Client` (Python) and `client.evals` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.evals.configs`, `client.evals.groups`, `client.evals.tasks`, `client.evals.templates`. The models these methods return are on [Datasets & evals response models](/docs/sdk/reference/datasets-evals-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`evals.test`](#evalstest) | Execute an evaluation template against supplied test inputs. | +| [`evals.configs.create`](#evalsconfigscreate) | Create a custom evaluation configuration from an eval template so it can be attached to an online evaluation task. | +| [`evals.configs.list`](#evalsconfigslist) | List the custom evaluation configurations available for online evaluation tasks. | +| [`evals.groups.get`](#evalsgroupsget) | Return an evaluation group by its identifier. | +| [`evals.groups.list`](#evalsgroupslist) | List evaluation groups in the current workspace. | +| [`evals.tasks.create`](#evalstaskscreate) | Create an online evaluation task. | +| [`evals.tasks.get`](#evalstasksget) | Return an online evaluation task by its identifier. | +| [`evals.tasks.list`](#evalstaskslist) | List online evaluation tasks in the current workspace. | +| [`evals.tasks.pause`](#evalstaskspause) | Pause a running online evaluation task by eval_task_id. | +| [`evals.tasks.resume`](#evalstasksresume) | Resume a paused online evaluation task by eval_task_id, scheduling remaining evaluations. | +| [`evals.tasks.update`](#evalstasksupdate) | Update and rerun an online evaluation task using eval_task_id and edit_type. | +| [`evals.templates.create`](#evalstemplatescreate) | Create an evaluation template. | +| [`evals.templates.get`](#evalstemplatesget) | Return an evaluation template by its identifier. | +| [`evals.templates.list`](#evalstemplateslist) | List evaluation templates using the supplied filters. | +| [`evals.templates.update`](#evalstemplatesupdate) | Update an existing evaluation template. | + +## client.evals + +### evals.test + +Execute an evaluation template against supplied test inputs. + + + +**MCP tool**: `test_evaluation` + + + +```python Python +result = client.evals.test( + config={}, + name="your-name", + output_type="your-output-type", +) +``` + +```typescript TypeScript +const result = await client.evals.test({ + config: {}, + name: "your-name", + output_type: "your-output-type", +}); +``` + + + + + +```python Python +client.evals.test( + *, + config: dict[str, Any], + name: str, + output_type: str, + model: str | None | NotGiven = NOT_GIVEN, + eval_tags: list[str] | None | NotGiven = NOT_GIVEN, + criteria: str | None | NotGiven = NOT_GIVEN, + multi_choice: bool | None | NotGiven = NOT_GIVEN, + choices: dict[str, Any] | None | NotGiven = NOT_GIVEN, + input_data_types: dict[str, Any] | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + check_internet: bool | None | NotGiven = NOT_GIVEN, + required_keys: list[str] | None | NotGiven = NOT_GIVEN, + template_type: str | None | NotGiven = NOT_GIVEN, + eval_type_id: str | None | NotGiven = NOT_GIVEN, + template_id: str | None | NotGiven = NOT_GIVEN, + eval_type: str | None | NotGiven = NOT_GIVEN, + error_localizer: bool | None | NotGiven = NOT_GIVEN, + reason_column: bool | None | NotGiven = NOT_GIVEN, + optional_keys: list[str] | None | NotGiven = NOT_GIVEN, + variable_keys: Any | None | NotGiven = NOT_GIVEN, + run_prompt_column: bool | None | NotGiven = NOT_GIVEN, + template_name: str | None | NotGiven = NOT_GIVEN, + mapping: dict[str, Any] | None | NotGiven = NOT_GIVEN, + output: str | None | NotGiven = NOT_GIVEN, + config_params_desc: dict[str, Any] | None | NotGiven = NOT_GIVEN, + config_params_option: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalExecutionResponseResult +``` + +```typescript TypeScript +client.evals.test(params: EvalsTestParams, options?: RequestOptions): Promise + +export interface EvalsTestParams { + config: Record; + name: string; + output_type: string; + model?: string | null; + eval_tags?: Array | null; + criteria?: string | null; + multi_choice?: boolean | null; + choices?: Record | null; + input_data_types?: Record | null; + description?: string | null; + check_internet?: boolean | null; + required_keys?: Array | null; + template_type?: string | null; + eval_type_id?: string | null; + template_id?: string | null; + eval_type?: string | null; + error_localizer?: boolean | null; + reason_column?: boolean | null; + optional_keys?: Array | null; + variable_keys?: JsonValue | null; + run_prompt_column?: boolean | null; + template_name?: string | null; + mapping?: Record | null; + output?: string | null; + config_params_desc?: Record | null; + config_params_option?: Record | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + +#### Returns + +[`EvalExecutionResponseResult`](/docs/sdk/reference/datasets-evals-models#evalexecutionresponseresult). + +## client.evals.configs + +TypeScript: `client.evals.configs`. + +### evals.configs.create + +Create a custom evaluation configuration from an eval template so it can be attached to an online evaluation task. Use when list_eval_configs has no entry for the template you want to run over spans. + + + +**MCP tool**: `create_eval_config` + + + +```python Python +result = client.evals.configs.create(eval_template="your-eval-template", project="your-project") +``` + +```typescript TypeScript +const result = await client.evals.configs.create({ + eval_template: "your-eval-template", + project: "your-project", +}); +``` + + + + + +```python Python +client.evals.configs.create( + *, + eval_template: str, + project: str, + name: str | None | NotGiven = NOT_GIVEN, + config: dict[str, Any] | None | NotGiven = NOT_GIVEN, + mapping: dict[str, Any] | None | NotGiven = NOT_GIVEN, + filters: dict[str, Any] | None | NotGiven = NOT_GIVEN, + error_localizer: bool | None | NotGiven = NOT_GIVEN, + kb_id: str | None | NotGiven = NOT_GIVEN, + model: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalsConfigsCreateResult +``` + +```typescript TypeScript +client.evals.configs.create(params: EvalsConfigsCreateParams, options?: RequestOptions): Promise + +export interface EvalsConfigsCreateParams { + eval_template: string; + project: string; + name?: string | null; + config?: Record | null; + mapping?: Record | null; + filters?: Record | null; + error_localizer?: boolean | null; + kb_id?: string | null; + model?: string | null; +} +``` + + + +#### Parameters + + + + + + + + + + + +#### Returns + +[`EvalsConfigsCreateResult`](/docs/sdk/reference/datasets-evals-models#evalsconfigscreateresult). + +### evals.configs.list + +List the custom evaluation configurations available for online evaluation tasks. The ids returned here are what create_eval_task takes in its `evals` argument - eval templates are a different object and their ids are not accepted there. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_eval_configs` + + + +```python Python +for item in client.evals.configs.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.evals.configs.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.evals.configs.list( + *, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.CustomEvalConfig] +``` + +```typescript TypeScript +client.evals.configs.list(params: EvalsConfigsListParams = {}, options?: RequestOptions): Pager + +export interface EvalsConfigsListParams { + /** Number of results to return per page. */ + limit?: number | null; +} +``` + + + +#### Parameters + + + Number of results to return per page. + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`CustomEvalConfig`](/docs/sdk/reference/datasets-evals-models#customevalconfig) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +## client.evals.groups + +TypeScript: `client.evals.groups`. + +### evals.groups.get + +Return an evaluation group by its identifier. + + + +**MCP tool**: `get_eval_group` + + + +```python Python +result = client.evals.groups.get("your-id") +``` + +```typescript TypeScript +const result = await client.evals.groups.get("your-id"); +``` + + + + + +```python Python +client.evals.groups.get( + id: str, + *, + name: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalGroup +``` + +```typescript TypeScript +client.evals.groups.get(id: string, params: EvalsGroupsGetParams = {}, options?: RequestOptions): Promise + +export interface EvalsGroupsGetParams { + name?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `id`. + + + +#### Returns + +[`EvalGroup`](/docs/sdk/reference/datasets-evals-models#evalgroup). + +### evals.groups.list + +List evaluation groups in the current workspace. + + + +**MCP tool**: `list_eval_groups` + + + +```python Python +result = client.evals.groups.list() +``` + +```typescript TypeScript +const result = await client.evals.groups.list(); +``` + + + + + +```python Python +client.evals.groups.list( + *, + name: str | None | NotGiven = NOT_GIVEN, + page_number: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.evals.groups.list(params: EvalsGroupsListParams = {}, options?: RequestOptions): Promise + +export interface EvalsGroupsListParams { + name?: string | null; + page_number?: number | null; + page_size?: number | null; +} +``` + + + +#### Parameters + + + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +## client.evals.tasks + +TypeScript: `client.evals.tasks`. + +### evals.tasks.create + +Create an online evaluation task. + + + +**MCP tool**: `create_eval_task` + + + +```python Python +result = client.evals.tasks.create( + project="your-project", + name="your-name", + sampling_rate=1.0, + run_type="continuous", + evals=[], +) +``` + +```typescript TypeScript +const result = await client.evals.tasks.create({ + project: "your-project", + name: "your-name", + sampling_rate: 1.0, + run_type: "continuous", + evals: [], +}); +``` + + + + + +```python Python +client.evals.tasks.create( + *, + project: str, + name: str, + sampling_rate: float, + run_type: Literal['continuous', 'historical'], + evals: list[str], + filters: dict[str, Any] | None | NotGiven = NOT_GIVEN, + last_run: str | None | NotGiven = NOT_GIVEN, + spans_limit: int | None | NotGiven = NOT_GIVEN, + row_type: Literal['spans', 'traces', 'sessions', 'voiceCalls'] | None | NotGiven = NOT_GIVEN, + status: Literal['pending', 'running', 'completed', 'failed', 'paused', 'deleted'] | None | NotGiven = NOT_GIVEN, + start_time: str | None | NotGiven = NOT_GIVEN, + end_time: str | None | NotGiven = NOT_GIVEN, + evals_details: dict[str, Any] | None | NotGiven = NOT_GIVEN, + failed_spans: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalTaskCreateResult +``` + +```typescript TypeScript +client.evals.tasks.create(params: EvalsTasksCreateParams, options?: RequestOptions): Promise + +export interface EvalsTasksCreateParams { + project: string; + name: string; + sampling_rate: number; + run_type: "continuous" | "historical"; + evals: Array; + filters?: Record | null; + last_run?: string | null; + spans_limit?: number | null; + row_type?: "spans" | "traces" | "sessions" | "voiceCalls" | null; + status?: "pending" | "running" | "completed" | "failed" | "paused" | "deleted" | null; + start_time?: string | null; + end_time?: string | null; + evals_details?: Record | null; + failed_spans?: Record | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + + + + + +#### Returns + +[`EvalTaskCreateResult`](/docs/sdk/reference/datasets-evals-models#evaltaskcreateresult). + +### evals.tasks.get + +Return an online evaluation task by its identifier. + + + +**MCP tool**: `get_eval_task` + + + +```python Python +result = client.evals.tasks.get("your-id") +``` + +```typescript TypeScript +const result = await client.evals.tasks.get("your-id"); +``` + + + + + +```python Python +client.evals.tasks.get( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalTask +``` + +```typescript TypeScript +client.evals.tasks.get(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `id`. + + +#### Returns + +[`EvalTask`](/docs/sdk/reference/datasets-evals-models#evaltask). + +### evals.tasks.list + +List online evaluation tasks in the current workspace. + + + +**MCP tool**: `list_eval_tasks` + + + +```python Python +result = client.evals.tasks.list() +``` + +```typescript TypeScript +const result = await client.evals.tasks.list(); +``` + + + + + +```python Python +client.evals.tasks.list( + *, + project_id: str | None | NotGiven = NOT_GIVEN, + name: str | None | NotGiven = NOT_GIVEN, + filters: str | None | NotGiven = NOT_GIVEN, + sort_params: str | None | NotGiven = NOT_GIVEN, + page_number: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models._EvalTaskListResultResponse +``` + +```typescript TypeScript +client.evals.tasks.list(params: EvalsTasksListParams = {}, options?: RequestOptions): Promise + +export interface EvalsTasksListParams { + project_id?: string | null; + name?: string | null; + filters?: string | null; + sort_params?: string | null; + page_number?: number | null; + page_size?: number | null; +} +``` + + + +#### Parameters + + + + + + + + +#### Returns + +[`_EvalTaskListResultResponse`](/docs/sdk/reference/datasets-evals-models#_evaltasklistresultresponse). + +### evals.tasks.pause + +Pause a running online evaluation task by eval_task_id. Already-launched evaluations may finish before the worker stops. + + + +**MCP tool**: `pause_eval_task` + + + +```python Python +result = client.evals.tasks.pause(eval_task_id="your-eval-task-id") +``` + +```typescript TypeScript +const result = await client.evals.tasks.pause({ eval_task_id: "your-eval-task-id" }); +``` + + + + + +```python Python +client.evals.tasks.pause( + *, + eval_task_id: str, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalTaskMessageResult +``` + +```typescript TypeScript +client.evals.tasks.pause(params: EvalsTasksPauseParams, options?: RequestOptions): Promise + +export interface EvalsTasksPauseParams { + eval_task_id: string; +} +``` + + + +#### Parameters + + + +#### Returns + +[`EvalTaskMessageResult`](/docs/sdk/reference/datasets-evals-models#evaltaskmessageresult). + +### evals.tasks.resume + +Resume a paused online evaluation task by eval_task_id, scheduling remaining evaluations. May incur evaluation charges. + + + +**MCP tool**: `resume_eval_task` + + + +```python Python +result = client.evals.tasks.resume(eval_task_id="your-eval-task-id") +``` + +```typescript TypeScript +const result = await client.evals.tasks.resume({ eval_task_id: "your-eval-task-id" }); +``` + + + + + +```python Python +client.evals.tasks.resume( + *, + eval_task_id: str, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalTaskMessageResult +``` + +```typescript TypeScript +client.evals.tasks.resume(params: EvalsTasksResumeParams, options?: RequestOptions): Promise + +export interface EvalsTasksResumeParams { + eval_task_id: string; +} +``` + + + +#### Parameters + + + +#### Returns + +[`EvalTaskMessageResult`](/docs/sdk/reference/datasets-evals-models#evaltaskmessageresult). + +### evals.tasks.update + +Update and rerun an online evaluation task using eval_task_id and edit_type. Pause a running task first. edit_rerun preserves existing results; fresh_run DELETES previous results and starts again. May incur evaluation charges. + + + +**MCP tool**: `update_eval_task` + + + +```python Python +result = client.evals.tasks.update(edit_type="edit_rerun", eval_task_id="your-eval-task-id") +``` + +```typescript TypeScript +const result = await client.evals.tasks.update({ + edit_type: "edit_rerun", + eval_task_id: "your-eval-task-id", +}); +``` + + + + + +```python Python +client.evals.tasks.update( + *, + edit_type: Literal['edit_rerun', 'fresh_run'], + eval_task_id: str, + name: str | None | NotGiven = NOT_GIVEN, + filters: dict[str, Any] | None | NotGiven = NOT_GIVEN, + sampling_rate: float | None | NotGiven = NOT_GIVEN, + spans_limit: int | None | NotGiven = NOT_GIVEN, + run_type: Literal['continuous', 'historical'] | None | NotGiven = NOT_GIVEN, + row_type: Literal['spans', 'traces', 'sessions', 'voiceCalls'] | None | NotGiven = NOT_GIVEN, + status: Literal['pending', 'running', 'completed', 'failed', 'paused', 'deleted'] | None | NotGiven = NOT_GIVEN, + evals: list[str] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalTaskUpdateResult +``` + +```typescript TypeScript +client.evals.tasks.update(params: EvalsTasksUpdateParams, options?: RequestOptions): Promise + +export interface EvalsTasksUpdateParams { + edit_type: "edit_rerun" | "fresh_run"; + eval_task_id: string; + name?: string | null; + filters?: Record | null; + sampling_rate?: number | null; + spans_limit?: number | null; + run_type?: "continuous" | "historical" | null; + row_type?: "spans" | "traces" | "sessions" | "voiceCalls" | null; + status?: "pending" | "running" | "completed" | "failed" | "paused" | "deleted" | null; + evals?: Array | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + +#### Returns + +[`EvalTaskUpdateResult`](/docs/sdk/reference/datasets-evals-models#evaltaskupdateresult). + +## client.evals.templates + +TypeScript: `client.evals.templates`. + +### evals.templates.create + +Create an evaluation template. + + + +**MCP tool**: `create_eval_template` + + + +```python Python +result = client.evals.templates.create() +``` + +```typescript TypeScript +const result = await client.evals.templates.create(); +``` + + + + + +```python Python +client.evals.templates.create( + *, + name: str | None | NotGiven = NOT_GIVEN, + is_draft: bool | None | NotGiven = NOT_GIVEN, + eval_type: Literal['llm', 'code', 'agent'] | None | NotGiven = NOT_GIVEN, + instructions: str | None | NotGiven = NOT_GIVEN, + model: str | None | NotGiven = NOT_GIVEN, + output_type: Literal['pass_fail', 'percentage', 'deterministic'] | None | NotGiven = NOT_GIVEN, + pass_threshold: float | None | NotGiven = NOT_GIVEN, + choice_scores: dict[str, Any] | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + tags: list[str] | None | NotGiven = NOT_GIVEN, + check_internet: bool | None | NotGiven = NOT_GIVEN, + code: str | None | NotGiven = NOT_GIVEN, + code_language: Literal['python', 'javascript'] | None | NotGiven = NOT_GIVEN, + messages: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + few_shot_examples: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + mode: Literal['auto', 'agent', 'quick'] | None | NotGiven = NOT_GIVEN, + tools: dict[str, Any] | None | NotGiven = NOT_GIVEN, + knowledge_bases: list[str] | None | NotGiven = NOT_GIVEN, + data_injection: dict[str, Any] | None | NotGiven = NOT_GIVEN, + summary: dict[str, Any] | None | NotGiven = NOT_GIVEN, + error_localizer_enabled: bool | None | NotGiven = NOT_GIVEN, + template_format: Literal['mustache', 'jinja'] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalTemplateCreateResponseResult +``` + +```typescript TypeScript +client.evals.templates.create(params: EvalsTemplatesCreateParams = {}, options?: RequestOptions): Promise + +export interface EvalsTemplatesCreateParams { + name?: string | null; + is_draft?: boolean | null; + eval_type?: "llm" | "code" | "agent" | null; + instructions?: string | null; + model?: string | null; + output_type?: "pass_fail" | "percentage" | "deterministic" | null; + pass_threshold?: number | null; + choice_scores?: Record | null; + description?: string | null; + tags?: Array | null; + check_internet?: boolean | null; + code?: string | null; + code_language?: "python" | "javascript" | null; + messages?: Array> | null; + few_shot_examples?: Array> | null; + mode?: "auto" | "agent" | "quick" | null; + tools?: Record | null; + knowledge_bases?: Array | null; + data_injection?: Record | null; + summary?: Record | null; + error_localizer_enabled?: boolean | null; + template_format?: "mustache" | "jinja" | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + + + + + + + + + + + + + +#### Returns + +[`EvalTemplateCreateResponseResult`](/docs/sdk/reference/datasets-evals-models#evaltemplatecreateresponseresult). + +### evals.templates.get + +Return an evaluation template by its identifier. + + + +**MCP tool**: `get_eval_template` + + + +```python Python +result = client.evals.templates.get("your-template-id") +``` + +```typescript TypeScript +const result = await client.evals.templates.get("your-template-id"); +``` + + + + + +```python Python +client.evals.templates.get( + template_id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalTemplateDetailResponseResult +``` + +```typescript TypeScript +client.evals.templates.get(templateId: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `template_id`. + + +#### Returns + +[`EvalTemplateDetailResponseResult`](/docs/sdk/reference/datasets-evals-models#evaltemplatedetailresponseresult). + +### evals.templates.list + +List evaluation templates using the supplied filters. + + + +**MCP tool**: `list_eval_templates` + + + +```python Python +result = client.evals.templates.list() +``` + +```typescript TypeScript +const result = await client.evals.templates.list(); +``` + + + + + +```python Python +client.evals.templates.list( + *, + page: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + owner_filter: Literal['all', 'user', 'system'] | None | NotGiven = NOT_GIVEN, + filters: dict[str, Any] | None | NotGiven = NOT_GIVEN, + sort_by: Literal['name', 'updated_at', 'created_at'] | None | NotGiven = NOT_GIVEN, + sort_order: Literal['asc', 'desc'] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalTemplateListResponseResult +``` + +```typescript TypeScript +client.evals.templates.list(params: EvalsTemplatesListParams = {}, options?: RequestOptions): Promise + +export interface EvalsTemplatesListParams { + page?: number | null; + page_size?: number | null; + search?: string | null; + owner_filter?: "all" | "user" | "system" | null; + filters?: Record | null; + sort_by?: "name" | "updated_at" | "created_at" | null; + sort_order?: "asc" | "desc" | null; +} +``` + + + +#### Parameters + + + + + + + + + +#### Returns + +[`EvalTemplateListResponseResult`](/docs/sdk/reference/datasets-evals-models#evaltemplatelistresponseresult). + +### evals.templates.update + +Update an existing evaluation template. + + + +**MCP tool**: `update_eval_template` + + + +```python Python +result = client.evals.templates.update("your-template-id") +``` + +```typescript TypeScript +const result = await client.evals.templates.update("your-template-id"); +``` + + + + + +```python Python +client.evals.templates.update( + template_id: str, + *, + name: str | None | NotGiven = NOT_GIVEN, + eval_type: Literal['llm', 'code', 'agent'] | None | NotGiven = NOT_GIVEN, + instructions: str | None | NotGiven = NOT_GIVEN, + model: str | None | NotGiven = NOT_GIVEN, + output_type: Literal['pass_fail', 'percentage', 'deterministic'] | None | NotGiven = NOT_GIVEN, + pass_threshold: float | None | NotGiven = NOT_GIVEN, + choice_scores: dict[str, Any] | None | NotGiven = NOT_GIVEN, + multi_choice: bool | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + tags: list[str] | None | NotGiven = NOT_GIVEN, + check_internet: bool | None | NotGiven = NOT_GIVEN, + code: str | None | NotGiven = NOT_GIVEN, + code_language: Literal['python', 'javascript'] | None | NotGiven = NOT_GIVEN, + messages: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + few_shot_examples: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + mode: Literal['auto', 'agent', 'quick'] | None | NotGiven = NOT_GIVEN, + tools: dict[str, Any] | None | NotGiven = NOT_GIVEN, + knowledge_bases: list[str] | None | NotGiven = NOT_GIVEN, + data_injection: dict[str, Any] | None | NotGiven = NOT_GIVEN, + summary: dict[str, Any] | None | NotGiven = NOT_GIVEN, + error_localizer_enabled: bool | None | NotGiven = NOT_GIVEN, + publish: bool | None | NotGiven = NOT_GIVEN, + template_format: Literal['mustache', 'jinja'] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.EvalTemplateUpdateResponseResult +``` + +```typescript TypeScript +client.evals.templates.update(templateId: string, params: EvalsTemplatesUpdateParams = {}, options?: RequestOptions): Promise + +export interface EvalsTemplatesUpdateParams { + name?: string | null; + eval_type?: "llm" | "code" | "agent" | null; + instructions?: string | null; + model?: string | null; + output_type?: "pass_fail" | "percentage" | "deterministic" | null; + pass_threshold?: number | null; + choice_scores?: Record | null; + multi_choice?: boolean | null; + description?: string | null; + tags?: Array | null; + check_internet?: boolean | null; + code?: string | null; + code_language?: "python" | "javascript" | null; + messages?: Array> | null; + few_shot_examples?: Array> | null; + mode?: "auto" | "agent" | "quick" | null; + tools?: Record | null; + knowledge_bases?: Array | null; + data_injection?: Record | null; + summary?: Record | null; + error_localizer_enabled?: boolean | null; + publish?: boolean | null; + template_format?: "mustache" | "jinja" | null; +} +``` + + + +#### Parameters + + + Positional argument `template_id`. + + + + + + + + + + + + + + + + + + + + + + + + + +#### Returns + +[`EvalTemplateUpdateResponseResult`](/docs/sdk/reference/datasets-evals-models#evaltemplateupdateresponseresult). diff --git a/src/pages/docs/sdk/reference/experiments.mdx b/src/pages/docs/sdk/reference/experiments.mdx new file mode 100644 index 000000000..00da2c8d9 --- /dev/null +++ b/src/pages/docs/sdk/reference/experiments.mdx @@ -0,0 +1,216 @@ +--- +title: "Experiments" +description: "Reference for client.experiments in the Future AGI Python and TypeScript SDKs: experiments.create, experiments.get, experiments.list." +--- + +`client.experiments` on `fi.Client` (Python) and `client.experiments` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Datasets & evals response models](/docs/sdk/reference/datasets-evals-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`experiments.create`](#experimentscreate) | Create and start an experiment. | +| [`experiments.get`](#experimentsget) | Return an experiment by its identifier. | +| [`experiments.list`](#experimentslist) | List experiments in the current workspace. | + +## client.experiments + +### experiments.create + +Create and start an experiment. The new experiment's id is returned inside the `result` message as `experiment_id=\`; pass it to get_experiment to follow the run. + + + +**MCP tool**: `create_experiment` + + + +```python Python +result = client.experiments.create( + name="your-name", + dataset_id="your-dataset-id", + prompt_config=[], + user_eval_metrics=[], +) +``` + +```typescript TypeScript +const result = await client.experiments.create({ + name: "your-name", + dataset_id: "your-dataset-id", + prompt_config: [], + user_eval_metrics: [], +}); +``` + + + + + +```python Python +client.experiments.create( + *, + name: str, + dataset_id: str, + prompt_config: list[dict[str, Any]], + user_eval_metrics: list[dict[str, Any]], + column_id: str | None | NotGiven = NOT_GIVEN, + experiment_type: Literal['llm', 'tts', 'stt', 'image'] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.experiments.create(params: ExperimentsCreateParams, options?: RequestOptions): Promise + +export interface ExperimentsCreateParams { + name: string; + dataset_id: string; + prompt_config: Array>; + user_eval_metrics: Array>; + column_id?: string | null; + experiment_type?: "llm" | "tts" | "stt" | "image" | null; +} +``` + + + +#### Parameters + + + + + + + + +#### Returns + +`string`. + +### experiments.get + +Return an experiment by its identifier. + + + +**MCP tool**: `get_experiment` + + + +```python Python +result = client.experiments.get("your-experiment-id") +``` + +```typescript TypeScript +const result = await client.experiments.get("your-experiment-id"); +``` + + + + + +```python Python +client.experiments.get( + experiment_id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.ExperimentDetailV2 +``` + +```typescript TypeScript +client.experiments.get(experimentId: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `experiment_id`. + + +#### Returns + +[`ExperimentDetailV2`](/docs/sdk/reference/datasets-evals-models#experimentdetailv2). + +### experiments.list + +List experiments in the current workspace. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_experiments` + + + +```python Python +for item in client.experiments.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.experiments.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.experiments.list( + *, + created_at: str | None | NotGiven = NOT_GIVEN, + status: str | None | NotGiven = NOT_GIVEN, + dataset_id: str | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + ordering: str | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.ExperimentListV2] +``` + +```typescript TypeScript +client.experiments.list(params: ExperimentsListParams = {}, options?: RequestOptions): Pager + +export interface ExperimentsListParams { + created_at?: string | null; + status?: string | null; + dataset_id?: string | null; + /** A search term. */ + search?: string | null; + /** Which field to use when ordering the results. */ + ordering?: string | null; + /** Number of results to return per page. */ + limit?: number | null; +} +``` + + + +#### Parameters + + + + + + A search term. + + + Which field to use when ordering the results. + + + Number of results to return per page. + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`ExperimentListV2`](/docs/sdk/reference/datasets-evals-models#experimentlistv2) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). diff --git a/src/pages/docs/sdk/reference/file-knowledge-bases.mdx b/src/pages/docs/sdk/reference/file-knowledge-bases.mdx new file mode 100644 index 000000000..9aaa849f1 --- /dev/null +++ b/src/pages/docs/sdk/reference/file-knowledge-bases.mdx @@ -0,0 +1,385 @@ +--- +title: "File knowledge bases" +description: "Reference for client.file_knowledge_bases in the Future AGI Python and TypeScript SDKs: file_knowledge_bases.create, file_knowledge_bases.delete, file_knowledge_bases.list, file_knowledge_bases.list_names, file_knowledge_bases.update, file_knowledge_bases.files.delete and 1 more." +--- + +`client.file_knowledge_bases` on `fi.Client` (Python) and `client.fileKnowledgeBases` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.file_knowledge_bases.files`. The models these methods return are on [Knowledge bases response models](/docs/sdk/reference/knowledge-bases-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`file_knowledge_bases.create`](#file_knowledge_basescreate) | Create a file knowledge base (the Knowledge Base page of the app), optionally uploading its first files (pdf, docx, txt, rtf). | +| [`file_knowledge_bases.delete`](#file_knowledge_basesdelete) | Delete file knowledge bases by id. | +| [`file_knowledge_bases.list`](#file_knowledge_baseslist) | List the file knowledge bases of the workspace as a table (name, file count, creator), without paging. | +| [`file_knowledge_bases.list_names`](#file_knowledge_baseslist_names) | Return the id and name of every file knowledge base, without paging. | +| [`file_knowledge_bases.update`](#file_knowledge_basesupdate) | Rename a file knowledge base and/or upload more files to it. | +| [`file_knowledge_bases.files.delete`](#file_knowledge_basesfilesdelete) | Delete files from a file knowledge base, by id or name, or all of them. | +| [`file_knowledge_bases.files.list`](#file_knowledge_basesfileslist) | List the files in a file knowledge base, with their processing status. | + +## client.file_knowledge_bases + +### file_knowledge_bases.create + +Create a file knowledge base (the Knowledge Base page of the app), optionally uploading its first files (pdf, docx, txt, rtf). + + + +**Multipart upload**: file parameters take a path, bytes or an open file + + + +```python Python +result = client.file_knowledge_bases.create(name="your-name") +``` + +```typescript TypeScript +const result = await client.fileKnowledgeBases.create({ name: "your-name" }); +``` + + + + + +```python Python +client.file_knowledge_bases.create( + *, + name: str, + files: list[FileInput] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.LegacyKnowledgeBaseCreateResult +``` + +```typescript TypeScript +client.fileKnowledgeBases.create(params: FileKnowledgeBasesCreateParams, options?: RequestOptions): Promise + +export interface FileKnowledgeBasesCreateParams { + name: string; + file?: Array; +} +``` + + + +#### Parameters + + + + +#### Returns + +[`LegacyKnowledgeBaseCreateResult`](/docs/sdk/reference/knowledge-bases-models#legacyknowledgebasecreateresult). + +### file_knowledge_bases.delete + +Delete file knowledge bases by id. + + + + + +```python Python +result = client.file_knowledge_bases.delete() +``` + +```typescript TypeScript +const result = await client.fileKnowledgeBases.delete(); +``` + + + + + +```python Python +client.file_knowledge_bases.delete( + *, + kb_ids: list[str] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.fileKnowledgeBases.delete(params: FileKnowledgeBasesDeleteParams = {}, options?: RequestOptions): Promise + +export interface FileKnowledgeBasesDeleteParams { + kb_ids?: Array | null; +} +``` + + + +#### Parameters + + + +#### Returns + +`string`. + +### file_knowledge_bases.list + +List the file knowledge bases of the workspace as a table (name, file count, creator), without paging. + + + + + +```python Python +result = client.file_knowledge_bases.list() +``` + +```typescript TypeScript +const result = await client.fileKnowledgeBases.list(); +``` + + + + + +```python Python +client.file_knowledge_bases.list( + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.LegacyKnowledgeBaseTableResult +``` + +```typescript TypeScript +client.fileKnowledgeBases.list(options?: RequestOptions): Promise +``` + + + +#### Parameters + +This method takes no parameters beyond the per-call `options`. + +#### Returns + +[`LegacyKnowledgeBaseTableResult`](/docs/sdk/reference/knowledge-bases-models#legacyknowledgebasetableresult). + +### file_knowledge_bases.list_names + +Return the id and name of every file knowledge base, without paging. + + + + + +```python Python +result = client.file_knowledge_bases.list_names() +``` + +```typescript TypeScript +const result = await client.fileKnowledgeBases.listNames(); +``` + + + + + +```python Python +client.file_knowledge_bases.list_names( + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.LegacyKnowledgeBaseListResult +``` + +```typescript TypeScript +client.fileKnowledgeBases.listNames(options?: RequestOptions): Promise +``` + + + +#### Parameters + +This method takes no parameters beyond the per-call `options`. + +#### Returns + +[`LegacyKnowledgeBaseListResult`](/docs/sdk/reference/knowledge-bases-models#legacyknowledgebaselistresult). + +### file_knowledge_bases.update + +Rename a file knowledge base and/or upload more files to it. + + + +**Multipart upload**: file parameters take a path, bytes or an open file + + + +```python Python +result = client.file_knowledge_bases.update(kb_id="your-kb-id") +``` + +```typescript TypeScript +const result = await client.fileKnowledgeBases.update({ kb_id: "your-kb-id" }); +``` + + + + + +```python Python +client.file_knowledge_bases.update( + *, + kb_id: str, + name: str | None | NotGiven = NOT_GIVEN, + files: list[FileInput] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.LegacyKnowledgeBaseMutationResult +``` + +```typescript TypeScript +client.fileKnowledgeBases.update(params: FileKnowledgeBasesUpdateParams, options?: RequestOptions): Promise + +export interface FileKnowledgeBasesUpdateParams { + kb_id: string; + name?: string | null; + file?: Array; +} +``` + + + +#### Parameters + + + + + +#### Returns + +[`LegacyKnowledgeBaseMutationResult`](/docs/sdk/reference/knowledge-bases-models#legacyknowledgebasemutationresult). + +## client.file_knowledge_bases.files + +TypeScript: `client.fileKnowledgeBases.files`. + +### file_knowledge_bases.files.delete + +Delete files from a file knowledge base, by id or name, or all of them. + + + + + +```python Python +result = client.file_knowledge_bases.files.delete() +``` + +```typescript TypeScript +const result = await client.fileKnowledgeBases.files.delete(); +``` + + + + + +```python Python +client.file_knowledge_bases.files.delete( + *, + kb_id: str | None | NotGiven = NOT_GIVEN, + delete_all: bool | None | NotGiven = NOT_GIVEN, + file_ids: list[str] | None | NotGiven = NOT_GIVEN, + excluded_file_ids: list[str] | None | NotGiven = NOT_GIVEN, + file_names: list[str] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> str +``` + +```typescript TypeScript +client.fileKnowledgeBases.files.delete(params: FileKnowledgeBasesFilesDeleteParams = {}, options?: RequestOptions): Promise + +export interface FileKnowledgeBasesFilesDeleteParams { + kb_id?: string | null; + delete_all?: boolean | null; + file_ids?: Array | null; + excluded_file_ids?: Array | null; + file_names?: Array | null; +} +``` + + + +#### Parameters + + + + + + + +#### Returns + +`string`. + +### file_knowledge_bases.files.list + +List the files in a file knowledge base, with their processing status. + + + + + +```python Python +result = client.file_knowledge_bases.files.list(kb_id="your-kb-id") +``` + +```typescript TypeScript +const result = await client.fileKnowledgeBases.files.list({ kb_id: "your-kb-id" }); +``` + + + + + +```python Python +client.file_knowledge_bases.files.list( + *, + kb_id: str, + search: str | None | NotGiven = NOT_GIVEN, + sort: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + page_number: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.LegacyKnowledgeBaseFilesResult +``` + +```typescript TypeScript +client.fileKnowledgeBases.files.list(params: FileKnowledgeBasesFilesListParams, options?: RequestOptions): Promise + +export interface FileKnowledgeBasesFilesListParams { + kb_id: string; + search?: string | null; + sort?: Array> | null; + page_number?: number | null; + page_size?: number | null; +} +``` + + + +#### Parameters + + + + + + + +#### Returns + +[`LegacyKnowledgeBaseFilesResult`](/docs/sdk/reference/knowledge-bases-models#legacyknowledgebasefilesresult). diff --git a/src/pages/docs/sdk/reference/gateway-models.mdx b/src/pages/docs/sdk/reference/gateway-models.mdx new file mode 100644 index 000000000..39cdcdcbe --- /dev/null +++ b/src/pages/docs/sdk/reference/gateway-models.mdx @@ -0,0 +1,19 @@ +--- +title: "Gateway response models" +description: "The 8 response models returned by the gateway resources of the Future AGI Python and TypeScript SDKs, with every field and its type." +--- + +The models returned by `client.gateway`, `client.models`, `client.provider_keys`, 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)). + +## Models + +| Model | Fields | +|---|---| +| `AgentccRequestLog` | `id: string`, `request_id: string`, `model: string`, `provider: string`, `resolved_model: string`, `latency_ms: integer`, `started_at: string`, `input_tokens: integer`, `output_tokens: integer`, `total_tokens: integer`, `cost: string`, `status_code: integer`, `is_stream: boolean`, `is_error: boolean`, `error_message: string`, `cache_hit: boolean`, `fallback_used: boolean`, `guardrail_triggered: boolean`, `api_key_id: string`, `user_id: string`, `session_id: string`, `routing_strategy: string`, `metadata: any`, `organization: string`, `workspace: string`, `created_at: string` | +| `AgentccSession` | `id: string`, `organization: string`, `session_id: string`, `name: string`, `status: string`, `metadata: any`, `created_at: string`, `updated_at: string` | +| `ApiKeyResponse` | `id: string`, `provider: string`, `organization: string`, `masked_actual_key: any` | +| `GatewayConfigProvider` | `id: string`, `name: string`, `display_name: string`, `base_url: string`, `api_format: string`, `api_path_prefix: string`, `models: any[]`, `is_active: boolean`, `default_timeout: integer`, `max_concurrent: integer`, `conn_pool_size: integer` | +| `GatewayConfigResult` | `id: string`, `organization: string`, `version: integer`, `guardrails: any`, `routing: any`, `cache: any`, `rate_limiting: any`, `budgets: any`, `cost_tracking: any`, `ip_acl: any`, `alerting: any`, `privacy: any`, `tool_policy: any`, `mcp: any`, `a2a: any`, `audit: any`, `model_database: any`, `model_map: any`, `is_active: boolean`, `created_by: string`, `change_description: string`, `created_at: string`, `updated_at: string`, `providers: any`, `gateway:` [`GatewayStatus`](#gatewaystatus) | +| `GatewayStatus` | `status: string` | +| `GatewaySummaryResult` | `id: string`, `name: string`, `base_url: string`, `status: string`, `provider_count: integer`, `model_count: integer` | +| `ModelHubPaginatedResponse` | `count: integer`, `next: string`, `previous: string`, `results: any[]` | diff --git a/src/pages/docs/sdk/reference/gateway.mdx b/src/pages/docs/sdk/reference/gateway.mdx new file mode 100644 index 000000000..8a304ec06 --- /dev/null +++ b/src/pages/docs/sdk/reference/gateway.mdx @@ -0,0 +1,487 @@ +--- +title: "Gateway" +description: "Reference for client.gateway in the Future AGI Python and TypeScript SDKs: gateway.analytics, gateway.config, gateway.list, gateway.guardrail_rules.list, gateway.request_logs.list, gateway.sessions.list and 1 more." +--- + +`client.gateway` on `fi.Client` (Python) and `client.gateway` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.gateway.guardrail_rules`, `client.gateway.request_logs`, `client.gateway.sessions`. The models these methods return are on [Gateway response models](/docs/sdk/reference/gateway-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`gateway.analytics`](#gatewayanalytics) | Return overview usage, latency, error, and cost analytics for the AI gateway. | +| [`gateway.config`](#gatewayconfig) | Return the effective configuration for an AI gateway. | +| [`gateway.list`](#gatewaylist) | List configured AI gateways. | +| [`gateway.guardrail_rules.list`](#gatewayguardrail_ruleslist) | Per-rule guardrail trigger breakdown - which guardrail rules exist and how often each has fired. | +| [`gateway.request_logs.list`](#gatewayrequest_logslist) | List request logs recorded by the AI gateway. | +| [`gateway.sessions.list`](#gatewaysessionslist) | List AI gateway sessions with their stats. | +| [`gateway.sessions.requests`](#gatewaysessionsrequests) | List every request log belonging to one gateway session. | + +## client.gateway + +### gateway.analytics + +Return overview usage, latency, error, and cost analytics for the AI gateway. + + + +**MCP tool**: `get_gateway_analytics` + + + +```python Python +result = client.gateway.analytics() +``` + +```typescript TypeScript +const result = await client.gateway.analytics(); +``` + + + + + +```python Python +client.gateway.analytics( + *, + start: str | None | NotGiven = NOT_GIVEN, + end: str | None | NotGiven = NOT_GIVEN, + granularity: str | None | NotGiven = NOT_GIVEN, + api_key_id: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.gateway.analytics(params: GatewayAnalyticsParams = {}, options?: RequestOptions): Promise + +export interface GatewayAnalyticsParams { + start?: string | null; + end?: string | null; + granularity?: string | null; + /** Gateway key id (not the API key's UUID primary key). */ + api_key_id?: string | null; +} +``` + + + +#### Parameters + + + + + + Gateway key id (not the API key's UUID primary key). + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### gateway.config + +Return the effective configuration for an AI gateway. + + + +**MCP tool**: `get_gateway_config` + + + +```python Python +result = client.gateway.config("your-id") +``` + +```typescript TypeScript +const result = await client.gateway.config("your-id"); +``` + + + + + +```python Python +client.gateway.config( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.GatewayConfigResult +``` + +```typescript TypeScript +client.gateway.config(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `id`. + + +#### Returns + +[`GatewayConfigResult`](/docs/sdk/reference/gateway-models#gatewayconfigresult). + +### gateway.list + +List configured AI gateways. + + + +**MCP tool**: `list_gateways` + + + +```python Python +result = client.gateway.list() +``` + +```typescript TypeScript +const result = await client.gateway.list(); +``` + + + + + +```python Python +client.gateway.list( + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> List[models.GatewaySummaryResult] +``` + +```typescript TypeScript +client.gateway.list(options?: RequestOptions): Promise> +``` + + + +#### Parameters + +This method takes no parameters beyond the per-call `options`. + +#### Returns + +A list of [`GatewaySummaryResult`](/docs/sdk/reference/gateway-models#gatewaysummaryresult). + +## client.gateway.guardrail_rules + +TypeScript: `client.gateway.guardrailRules`. + +### gateway.guardrail_rules.list + +Per-rule guardrail trigger breakdown - which guardrail rules exist and how often each has fired. Request logs report guardrail_triggered but not which rule caused it; this is what turns "the request was blocked" into "the PII rule blocked it". + + + +**MCP tool**: `list_guardrail_rules` + + + +```python Python +result = client.gateway.guardrail_rules.list() +``` + +```typescript TypeScript +const result = await client.gateway.guardrailRules.list(); +``` + + + + + +```python Python +client.gateway.guardrail_rules.list( + *, + page: int | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.gateway.guardrailRules.list(params: GatewayGuardrailRulesListParams = {}, options?: RequestOptions): Promise + +export interface GatewayGuardrailRulesListParams { + /** A page number within the paginated result set. */ + page?: number | null; + /** Number of results to return per page. */ + limit?: number | null; +} +``` + + + +#### Parameters + + + A page number within the paginated result set. + + + Number of results to return per page. + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +## client.gateway.request_logs + +TypeScript: `client.gateway.requestLogs`. + +### gateway.request_logs.list + +List request logs recorded by the AI gateway. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_gateway_request_logs` + + + +```python Python +for item in client.gateway.request_logs.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.gateway.requestLogs.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.gateway.request_logs.list( + *, + limit: int | None | NotGiven = NOT_GIVEN, + user_id: str | None | NotGiven = NOT_GIVEN, + session_id: str | None | NotGiven = NOT_GIVEN, + api_key_id: str | None | NotGiven = NOT_GIVEN, + request_id: str | None | NotGiven = NOT_GIVEN, + model: str | None | NotGiven = NOT_GIVEN, + provider: str | None | NotGiven = NOT_GIVEN, + status_code: str | None | NotGiven = NOT_GIVEN, + min_status_code: int | None | NotGiven = NOT_GIVEN, + max_status_code: int | None | NotGiven = NOT_GIVEN, + is_error: bool | None | NotGiven = NOT_GIVEN, + cache_hit: bool | None | NotGiven = NOT_GIVEN, + fallback_used: bool | None | NotGiven = NOT_GIVEN, + guardrail_triggered: bool | None | NotGiven = NOT_GIVEN, + is_stream: bool | None | NotGiven = NOT_GIVEN, + started_after: str | None | NotGiven = NOT_GIVEN, + started_before: str | None | NotGiven = NOT_GIVEN, + min_latency: int | None | NotGiven = NOT_GIVEN, + max_latency: int | None | NotGiven = NOT_GIVEN, + min_cost: float | None | NotGiven = NOT_GIVEN, + max_cost: float | None | NotGiven = NOT_GIVEN, + min_tokens: int | None | NotGiven = NOT_GIVEN, + max_tokens: int | None | NotGiven = NOT_GIVEN, + q: str | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + ordering: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.AgentccRequestLog] +``` + +```typescript TypeScript +client.gateway.requestLogs.list(params: GatewayRequestLogsListParams = {}, options?: RequestOptions): Pager + +export interface GatewayRequestLogsListParams { + limit?: number | null; + user_id?: string | null; + session_id?: string | null; + /** Gateway key id (not the API key's UUID primary key). */ + api_key_id?: string | null; + request_id?: string | null; + /** Comma-separated model names. */ + model?: string | null; + /** Comma-separated provider names. */ + provider?: string | null; + /** Comma-separated HTTP status codes. */ + status_code?: string | null; + min_status_code?: number | null; + max_status_code?: number | null; + is_error?: boolean | null; + cache_hit?: boolean | null; + fallback_used?: boolean | null; + guardrail_triggered?: boolean | null; + is_stream?: boolean | null; + started_after?: string | null; + started_before?: string | null; + min_latency?: number | null; + max_latency?: number | null; + min_cost?: number | null; + max_cost?: number | null; + min_tokens?: number | null; + max_tokens?: number | null; + q?: string | null; + search?: string | null; + ordering?: string | null; +} +``` + + + +#### Parameters + + + + + + Gateway key id (not the API key's UUID primary key). + + + + Comma-separated model names. + + + Comma-separated provider names. + + + Comma-separated HTTP status codes. + + + + + + + + + + + + + + + + + + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`AgentccRequestLog`](/docs/sdk/reference/gateway-models#agentccrequestlog) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +## client.gateway.sessions + +TypeScript: `client.gateway.sessions`. + +### gateway.sessions.list + +List AI gateway sessions with their stats. These are gateway sessions, distinct from the tracing sessions returned by list_sessions. Use this to obtain a session id for list_gateway_session_requests. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_gateway_sessions` + + + +```python Python +for item in client.gateway.sessions.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.gateway.sessions.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.gateway.sessions.list( + *, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.AgentccSession] +``` + +```typescript TypeScript +client.gateway.sessions.list(params: GatewaySessionsListParams = {}, options?: RequestOptions): Pager + +export interface GatewaySessionsListParams { + /** Number of results to return per page. */ + limit?: number | null; +} +``` + + + +#### Parameters + + + Number of results to return per page. + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`AgentccSession`](/docs/sdk/reference/gateway-models#agentccsession) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### gateway.sessions.requests + +List every request log belonging to one gateway session. Request logs carry no trace id, so grouping by session is the way to see what else happened around a failed request. + + + +**MCP tool**: `list_gateway_session_requests` + + + +```python Python +result = client.gateway.sessions.requests("your-id") +``` + +```typescript TypeScript +const result = await client.gateway.sessions.requests("your-id"); +``` + + + + + +```python Python +client.gateway.sessions.requests( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.gateway.sessions.requests(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this agentcc session. + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. diff --git a/src/pages/docs/sdk/reference/index.mdx b/src/pages/docs/sdk/reference/index.mdx new file mode 100644 index 000000000..28d8ae5a6 --- /dev/null +++ b/src/pages/docs/sdk/reference/index.mdx @@ -0,0 +1,260 @@ +--- +title: "Platform SDK reference" +description: "Every method of the Future AGI platform client in Python and TypeScript: the client, conventions for arguments, pagination, errors and strict mode, and one page per resource." +--- + + +- One client, every API: `fi.Client` (Python, `pip install futureagi`) and `Client` from `@future-agi/sdk` (TypeScript) +- 162 methods across 25 resources, generated from the API contract; each page lists parameters, return types and the REST endpoint +- Omitted arguments are not sent, `None` / `null` is; list calls return pagers; HTTP errors raise typed exceptions + + +The platform client is generated from the Future AGI API contract, so every REST operation has one method with the same name in Python and TypeScript. This reference is generated from the same source as the SDKs. For narrative guides, see the [SDK overview](/docs/sdk). + +## The client + +Credentials come from the constructor or from the environment: `FI_API_KEY`, `FI_SECRET_KEY`, and optionally `FI_BASE_URL` and `FI_WORKSPACE_ID`. + + + +```python Python +from fi import Client + +client = Client() # or Client(api_key=..., secret_key=..., base_url=...) +for dataset in client.datasets.list(): + print(dataset.name) +``` + +```typescript TypeScript +import { Client } from "@future-agi/sdk"; + +const client = new Client(); // or new Client({ apiKey, secretKey, baseUrl }) +for await (const dataset of client.datasets.list()) { + console.log(dataset.name); +} +``` + + + +Python also ships `AsyncClient` with the same methods, awaited (`await client.datasets.get(...)`, `async for` over pagers). + + + Defaults to `FI_API_KEY`. + + + Defaults to `FI_SECRET_KEY`. + + + Defaults to `FI_BASE_URL`, then `https://api.futureagi.com`. + + + Defaults to `FI_WORKSPACE_ID`. Sent as `X-Workspace-Id`. + + + Per-request timeout: seconds in Python (default 60), milliseconds in TypeScript (default 60000). + + + Default 2. Retries 429 on every call, and timeouts and 5xx on calls that are safe to repeat. + + + Sent with every request. + + + Python only. Reject a response that misses a field the contract marks required (see Strict mode). + + + Python: an `httpx.Client` (or `httpx.AsyncClient`) to use instead of the SDK's own. TypeScript: a replacement for the global `fetch`. + + +## Conventions + +### Arguments + +Path parameters are positional; every other parameter is a keyword argument in Python and a field of the `params` object in TypeScript. An argument you leave out is not sent. Passing `None` (Python) or `null` (TypeScript) sends `null`, which clears a nullable field. In Python the omitted-argument sentinel is `fi.platform.NOT_GIVEN`. + +A `PATCH` is always a partial update: send only the fields you want to change. + +Fields the contract does not describe yet go through the escape hatches: `extra_query=` and `extra_body=` in Python, `options.extraQuery` and `options.extraBody` in TypeScript. + +### Per-call options + +Every method accepts `options` (`fi.platform.RequestOptions` / `RequestOptions`) with `headers`, `timeout` and `max_retries` / `maxRetries` overrides for that one call. + +### Pagination + +A method marked *paginated* returns a pager instead of a list and fetches pages as you iterate. Python `SyncPager` / `AsyncPager`: iterate, or `first_page()` for one `Page` (`items`, `number`, `raw`), or `to_list(limit=None)`. TypeScript `Pager`: `for await`, or `firstPage()`, or `toArray(limit?)`. + +### Responses + +Responses are parsed into models (`fi.platform.models` / `@future-agi/sdk/platform/models`), documented on the response-models page of each area below. Parsing is tolerant: a field the backend leaves out is `None` / `undefined`, an extra field is kept. The backend's `{status, result}` envelope is unwrapped for you. + +### Strict mode + +`Client(strict_responses=True)` (Python) raises `ResponseValidationError` when a response misses a field the contract marks required. Use it in tests to catch contract drift; leave it off in production. + +### Errors + +HTTP errors raise a subclass of `APIError` (`fi.platform` / `@future-agi/sdk`) with `status_code` / `status`, `body`, `detail` and `request_id` / `requestId`: + +| Status | Error | +|---|---| +| 400 | `BadRequestError` | +| 401 | `AuthenticationError` | +| 402 | `PaymentRequiredError` | +| 403 | `PermissionDeniedError` | +| 404 | `NotFoundError` | +| 409 | `ConflictError` | +| 422 | `UnprocessableEntityError` | +| 429 | `RateLimitError` | +| 5xx | `InternalServerError` | + +Network failures raise `APIConnectionError`. All of them extend `FutureAGIError`. + +### Stability + +A method marked **Beta** may change without notice; the first call emits a `BetaWarning` (Python) or a console warning (TypeScript). + +### Any endpoint + +`client.request(method, path, ...)` calls any endpoint under the base URL with the client's authentication, retries and error handling, for operations this reference does not list yet. + +## Resources + +### Account + + + + `client.account`: 1 method. + + + `client.workspaces`: 2 methods. + + + `client.usage`: 1 method. + + + What the account methods return. + + + +### Datasets & evals + + + + `client.datasets`: 20 methods. + + + `client.evals`: 15 methods. + + + `client.experiments`: 3 methods. + + + `client.optimizations`: 3 methods. + + + What the datasets & evals methods return. + + + +### Prompts + + + + `client.prompts`: 22 methods. + + + What the prompts methods return. + + + +### Observability + + + + `client.projects`: 2 methods. + + + `client.traces`: 4 methods. + + + `client.spans`: 2 methods. + + + `client.sessions`: 2 methods. + + + `client.dashboards`: 13 methods. + + + `client.error_clusters`: 2 methods. + + + `client.alerts`: 2 methods. + + + What the observability methods return. + + + +### Annotation + + + + `client.annotation_queues`: 23 methods. + + + `client.annotations`: 5 methods. + + + `client.scores`: 3 methods. + + + What the annotation methods return. + + + +### Simulation + + + + `client.agents`: 5 methods. + + + `client.simulation`: 11 methods. + + + What the simulation methods return. + + + +### Knowledge bases + + + + `client.knowledge_bases`: 5 methods. + + + `client.file_knowledge_bases`: 7 methods. + + + What the knowledge bases methods return. + + + +### Gateway + + + + `client.gateway`: 7 methods. + + + `client.models`: 1 method. + + + `client.provider_keys`: 1 method. + + + What the gateway methods return. + + diff --git a/src/pages/docs/sdk/reference/knowledge-bases-models.mdx b/src/pages/docs/sdk/reference/knowledge-bases-models.mdx new file mode 100644 index 000000000..2d6bb74c4 --- /dev/null +++ b/src/pages/docs/sdk/reference/knowledge-bases-models.mdx @@ -0,0 +1,21 @@ +--- +title: "Knowledge bases response models" +description: "The 10 response models returned by the knowledge bases resources of the Future AGI Python and TypeScript SDKs, with every field and its type." +--- + +The models returned by `client.knowledge_bases`, `client.file_knowledge_bases`, 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)). + +## Models + +| Model | Fields | +|---|---| +| `KnowledgeBaseItem` | `id: string`, `name: string`, `embedding_model: string`, `chunk_size: integer`, `organization: string`, `created_at: string`, `updated_at: string` | +| `LegacyKnowledgeBaseCreateResult` | `detail: string`, `kb_id: string`, `kb_name: string`, `file_ids: string[]` | +| `LegacyKnowledgeBaseFileRow` | `id: string`, `name: string`, `file_size: integer`, `status: string`, `updated: string`, `updated_by: string`, `error: string` | +| `LegacyKnowledgeBaseFilesResult` | `table_data:` [`LegacyKnowledgeBaseFileRow`](#legacyknowledgebasefilerow)[], `last_updated: string`, `status: string`, `status_count: integer`, `total_rows: integer` | +| `LegacyKnowledgeBaseListResult` | `table_data:` [`LegacyKnowledgeBaseOption`](#legacyknowledgebaseoption)[] | +| `LegacyKnowledgeBaseMutationResult` | `id: string`, `name: string`, `organization: string`, `status: string`, `files: string[]`, `updated_at: string`, `created_by: string`, `last_error: string` | +| `LegacyKnowledgeBaseOption` | `id: string`, `name: string` | +| `LegacyKnowledgeBaseTableColumn` | `id: string`, `name: string` | +| `LegacyKnowledgeBaseTableResult` | `column_config:` [`LegacyKnowledgeBaseTableColumn`](#legacyknowledgebasetablecolumn)[], `table_data:` [`LegacyKnowledgeBaseTableRow`](#legacyknowledgebasetablerow)[], `total_rows: integer` | +| `LegacyKnowledgeBaseTableRow` | `id: string`, `name: string`, `files_uploaded: integer`, `status: string`, `error: string`, `updated_at: string`, `created_by: string` | diff --git a/src/pages/docs/sdk/reference/knowledge-bases.mdx b/src/pages/docs/sdk/reference/knowledge-bases.mdx new file mode 100644 index 000000000..359db748c --- /dev/null +++ b/src/pages/docs/sdk/reference/knowledge-bases.mdx @@ -0,0 +1,289 @@ +--- +title: "Knowledge bases" +description: "Reference for client.knowledge_bases in the Future AGI Python and TypeScript SDKs: knowledge_bases.create, knowledge_bases.delete, knowledge_bases.get, knowledge_bases.list, knowledge_bases.update." +--- + +`client.knowledge_bases` on `fi.Client` (Python) and `client.knowledgeBases` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Knowledge bases response models](/docs/sdk/reference/knowledge-bases-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`knowledge_bases.create`](#knowledge_basescreate) | Create a knowledge base with a name, an embedding model and a chunk size; it appears in knowledge_bases.list and knowledge_bases.get. | +| [`knowledge_bases.delete`](#knowledge_basesdelete) | Delete a knowledge base. | +| [`knowledge_bases.get`](#knowledge_basesget) | Return a knowledge base and its configuration. | +| [`knowledge_bases.list`](#knowledge_baseslist) | List knowledge bases (the RAG stores with an embedding model and a chunk size) in the current workspace. | +| [`knowledge_bases.update`](#knowledge_basesupdate) | Update the name, embedding model or chunk size of a knowledge base (a partial update). | + +## client.knowledge_bases + +### knowledge_bases.create + +Create a knowledge base with a name, an embedding model and a chunk size; it appears in knowledge_bases.list and knowledge_bases.get. + + + + + +```python Python +result = client.knowledge_bases.create(name="your-name", chunk_size=1) +``` + +```typescript TypeScript +const result = await client.knowledgeBases.create({ + name: "your-name", + chunk_size: 1, +}); +``` + + + + + +```python Python +client.knowledge_bases.create( + *, + name: str, + chunk_size: int, + embedding_model: Literal['BAAI/bge-small-en-v1.5'] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.KnowledgeBaseItem +``` + +```typescript TypeScript +client.knowledgeBases.create(params: KnowledgeBasesCreateParams, options?: RequestOptions): Promise + +export interface KnowledgeBasesCreateParams { + name: string; + chunk_size: number; + embedding_model?: "BAAI/bge-small-en-v1.5" | null; +} +``` + + + +#### Parameters + + + + + +#### Returns + +[`KnowledgeBaseItem`](/docs/sdk/reference/knowledge-bases-models#knowledgebaseitem). + +### knowledge_bases.delete + +Delete a knowledge base. + + + + + +```python Python +result = client.knowledge_bases.delete("your-id") +``` + +```typescript TypeScript +const result = await client.knowledgeBases.delete("your-id"); +``` + + + + + +```python Python +client.knowledge_bases.delete( + id: str, + *, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.knowledgeBases.delete(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this knowledge base. + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### knowledge_bases.get + +Return a knowledge base and its configuration. + + + +**MCP tool**: `get_knowledge_base` + + + +```python Python +result = client.knowledge_bases.get("your-id") +``` + +```typescript TypeScript +const result = await client.knowledgeBases.get("your-id"); +``` + + + + + +```python Python +client.knowledge_bases.get( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.KnowledgeBaseItem +``` + +```typescript TypeScript +client.knowledgeBases.get(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this knowledge base. + + +#### Returns + +[`KnowledgeBaseItem`](/docs/sdk/reference/knowledge-bases-models#knowledgebaseitem). + +### knowledge_bases.list + +List knowledge bases (the RAG stores with an embedding model and a chunk size) in the current workspace. Knowledge bases built from uploaded files are a separate store, see file_knowledge_bases. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_knowledge_bases` + + + +```python Python +for item in client.knowledge_bases.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.knowledgeBases.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.knowledge_bases.list( + *, + search: str | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.KnowledgeBaseItem] +``` + +```typescript TypeScript +client.knowledgeBases.list(params: KnowledgeBasesListParams = {}, options?: RequestOptions): Pager + +export interface KnowledgeBasesListParams { + /** A search term. */ + search?: string | null; + /** Number of results to return per page. */ + limit?: number | null; +} +``` + + + +#### Parameters + + + A search term. + + + Number of results to return per page. + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`KnowledgeBaseItem`](/docs/sdk/reference/knowledge-bases-models#knowledgebaseitem) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### knowledge_bases.update + +Update the name, embedding model or chunk size of a knowledge base (a partial update). + + + + + +```python Python +result = client.knowledge_bases.update("your-id") +``` + +```typescript TypeScript +const result = await client.knowledgeBases.update("your-id"); +``` + + + + + +```python Python +client.knowledge_bases.update( + id: str, + *, + name: str | None | NotGiven = NOT_GIVEN, + embedding_model: Literal['BAAI/bge-small-en-v1.5'] | None | NotGiven = NOT_GIVEN, + chunk_size: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.KnowledgeBaseItem +``` + +```typescript TypeScript +client.knowledgeBases.update(id: string, params: KnowledgeBasesUpdateParams = {}, options?: RequestOptions): Promise + +export interface KnowledgeBasesUpdateParams { + name?: string | null; + embedding_model?: "BAAI/bge-small-en-v1.5" | null; + chunk_size?: number | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this knowledge base. + + + + + +#### Returns + +[`KnowledgeBaseItem`](/docs/sdk/reference/knowledge-bases-models#knowledgebaseitem). diff --git a/src/pages/docs/sdk/reference/models.mdx b/src/pages/docs/sdk/reference/models.mdx new file mode 100644 index 000000000..19e384757 --- /dev/null +++ b/src/pages/docs/sdk/reference/models.mdx @@ -0,0 +1,56 @@ +--- +title: "Models" +description: "Reference for client.models in the Future AGI Python and TypeScript SDKs: models.list." +--- + +`client.models` on `fi.Client` (Python) and `client.models` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Gateway response models](/docs/sdk/reference/gateway-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`models.list`](#modelslist) | List the LLM models available to prompts and evaluations, with their providers. | + +## client.models + +### models.list + +List the LLM models available to prompts and evaluations, with their providers. + + + + + +```python Python +result = client.models.list() +``` + +```typescript TypeScript +const result = await client.models.list(); +``` + + + + + +```python Python +client.models.list( + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.ModelHubPaginatedResponse +``` + +```typescript TypeScript +client.models.list(options?: RequestOptions): Promise +``` + + + +#### Parameters + +This method takes no parameters beyond the per-call `options`. + +#### Returns + +[`ModelHubPaginatedResponse`](/docs/sdk/reference/gateway-models#modelhubpaginatedresponse). diff --git a/src/pages/docs/sdk/reference/observability-models.mdx b/src/pages/docs/sdk/reference/observability-models.mdx new file mode 100644 index 000000000..0ad92c262 --- /dev/null +++ b/src/pages/docs/sdk/reference/observability-models.mdx @@ -0,0 +1,57 @@ +--- +title: "Observability response models" +description: "The 46 response models returned by the observability resources of the Future AGI Python and TypeScript SDKs, with every field and its type." +--- + +The models returned by `client.projects`, `client.traces`, `client.spans`, `client.sessions`, `client.dashboards`, `client.error_clusters`, `client.alerts`, 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)). + +## Models + +| Model | Fields | +|---|---| +| `Dashboard` | `id: string`, `name: string`, `description: string`, `workspace: string`, `created_by:` [`User`](#user), `updated_by:` [`User`](#user), `created_at: string`, `updated_at: string`, `widget_count: any` | +| `DashboardDetail` | `id: string`, `name: string`, `description: string`, `workspace: string`, `created_by:` [`User`](#user), `updated_by:` [`User`](#user), `created_at: string`, `updated_at: string`, `widgets: any` | +| `DashboardFilterValueOption` | `value: any JSON value`, `label: string`, `type: string`, `name: string`, `email: string`, `description: string` | +| `DashboardFilterValuesResult` | `query_exact: boolean`, `values:` [`DashboardFilterValueOption`](#dashboardfiltervalueoption)[], `query_complete: boolean`, `query_status: string`, `query_error_code: string`, `query_window_start: string`, `query_window_end: string`, `query_window_mode: string`, `query_count: integer`, `has_more: boolean`, `browse_status: string`, `next_cursor: string`, `attribute_type: string`, `attribute_types: string[]`, `attribute_types_exact: boolean`, `catalog_epoch: integer`, `catalog_revision: integer`, `activation_fingerprint: string`, `query_provenance: string` | +| `DashboardMetricCatalogItem` | `name: string`, `property_id: string`, `property_kind: string`, `display_name: string`, `category: string`, `source: string`, `sources: string[]`, `type: string`, `unit: string`, `output_type: string`, `eval_template_id: string`, `role: string`, `choices: any JSON value[]`, `choice_options: any JSON value[]`, `allowed_aggregations: string[]`, `data_type: string`, `attribute_types: string[]`, `attribute_types_exact: boolean` | +| `DashboardMetricsCatalogResult` | `metrics:` [`DashboardMetricCatalogItem`](#dashboardmetriccatalogitem)[], `total: integer`, `total_is_exact: boolean`, `category_counts: any`, `category_counts_exact: boolean`, `page: integer`, `page_size: integer`, `has_more: boolean`, `next_cursor: string`, `catalog_epoch: integer`, `catalog_revision: integer`, `activation_fingerprint: string`, `query_complete: boolean`, `query_exact: boolean`, `query_status: string`, `query_provenance: string` | +| `DashboardQueryMetricResult` | `id: string`, `name: string`, `aggregation: string`, `unit: string`, `series:` [`DashboardQuerySeries`](#dashboardqueryseries)[], `series_total: integer`, `series_truncated: boolean`, `query_complete: boolean`, `query_sampled: boolean`, `query_status: string`, `query_error_code: string`, `query_exact: boolean`, `query_provenance: string`, `query_sampling_strategy: string`, `query_sampling_interval_seconds: integer`, `query_sample_limit: integer`, `query_sample_per_bucket: integer` | +| `DashboardQueryResult` | `metrics:` [`DashboardQueryMetricResult`](#dashboardquerymetricresult)[], `time_range:` [`DashboardQueryTimeRangeResult`](#dashboardquerytimerangeresult), `granularity: string`, `query_complete: boolean`, `query_status: string`, `query_sampled: boolean`, `query_exact: boolean`, `query_provenance: string`, `query_error_code: string`, `query_sampling_strategy: string`, `query_count: integer`, `query_rows_returned: integer`, `query_elapsed_ms: number`, `query_completed_at: string`, `query_cached: boolean`, `query_refresh_failed: boolean`, `query_refreshing: boolean`, `query_snapshot_version_ceiling: integer`, `query_snapshot_capture_count: integer`, `query_snapshot_relation_count: integer` | +| `DashboardQuerySeries` | `name: string`, `data:` [`DashboardQuerySeriesPoint`](#dashboardqueryseriespoint)[] | +| `DashboardQuerySeriesPoint` | `timestamp: string`, `value: number` | +| `DashboardQueryTimeRangeResult` | `start: string`, `end: string` | +| `DashboardWidget` | `id: string`, `name: string`, `description: string`, `position: integer`, `width: integer`, `height: integer`, `query_config: any`, `chart_config: any`, `created_by: string`, `created_at: string`, `updated_at: string` | +| `ErrorName` | `name: string`, `type: string` | +| `EvalRollup` | `scope: string`, `evals:` [`EvalRollupEval`](#evalrollupeval)[], `error: boolean` | +| `EvalRollupEval` | `eval_config_id: string`, `eval_name: string`, `output_type: string`, `template_type: string`, `target_type: string`, `choices_map: any JSON value`, `aggregate: any JSON value`, `spans:` [`EvalRollupSpan`](#evalrollupspan)[], `error: boolean` | +| `EvalRollupSpan` | `span_id: string`, `span_name: string`, `value: any JSON value`, `explanation: string`, `error: boolean`, `status: string`, `eval_config_id: string` | +| `FeedDetailCore` | `row:` [`FeedListRow`](#feedlistrow), `description: string`, `success_trace:` [`TracePreview`](#tracepreview), `representative_trace:` [`TracePreview`](#tracepreview), `rca:` [`RcaSummary`](#rcasummary) | +| `FeedListResponse` | `data:` [`FeedListRow`](#feedlistrow)[], `total: integer`, `limit: integer`, `offset: integer` | +| `FeedListRow` | `severity_assessment_status: string`, `severity_source: string`, `severity_reason: string`, `cluster_id: string`, `source: string`, `modality: string`, `error:` [`ErrorName`](#errorname), `status: string`, `severity: string`, `occurrences: integer`, `trace_count: integer`, `fix_layer: string`, `users_affected: integer`, `sessions: integer`, `first_seen: string`, `last_seen: string`, `trends:` [`TrendPoint`](#trendpoint)[], `assignees: string[]`, `model: string`, `model_version: string`, `project: string`, `project_id: string`, `environment: string`, `eval_score: number`, `trace_id: string`, `external_issue_url: string`, `external_issue_id: string` | +| `ObservationSpanDetailResult` | `observation_span: any`, `evals_metrics: any`, `enrichment: any` | +| `Organization` | `id: string`, `created_at: string`, `name: string`, `display_name: string`, `is_new: boolean`, `ws_enabled: boolean`, `region: string`, `require_2fa: boolean`, `require_2fa_grace_period_days: integer`, `require_2fa_enforced_at: string` | +| `ProjectDetailResult` | `id: string`, `model_type: string`, `name: string`, `trace_type: string`, `metadata: any`, `organization: string`, `workspace: string`, `created_at: string`, `updated_at: string`, `config: any JSON value`, `source: string`, `session_config: any JSON value`, `tags: any JSON value`, `sampling_rate: number` | +| `RcaSummary` | `synthesis: string`, `fix: string`, `confidence: string`, `evidence_trace_ids: string[]`, `analyzed_at: string`, `failures_at_run: integer`, `trace:` [`RcaTrailStep`](#rcatrailstep)[] | +| `RcaTrailStep` | `type: string`, `text: string`, `call_id: string`, `tool: string`, `args: any`, `result: any`, `synthesis: string`, `fix: string`, `confidence: string` | +| `SpanListColumnConfig` | `id: string`, `name: string`, `is_visible: boolean`, `group_by: string`, `output_type: string`, `reverse_output: boolean`, `annotation_label_type: string`, `choices: string[]`, `settings: any JSON value`, `choices_map: any JSON value`, `eval_template_id: string`, `target_type: string`, `annotators: any JSON value`, `source_field: string`, `parent_eval_id: string`, `property_id: string`, `property_kind: string`, `property_source: string` | +| `SpanListMetadata` | `total_rows: integer`, `total_rows_exact: integer`, `total_rows_is_lower_bound: boolean`, `has_more: boolean`, `next_cursor: string`, `next_cursor_fingerprint: string`, `query_complete: boolean`, `query_status: string`, `query_error_code: string`, `query_elapsed_ms: number`, `query_count: integer`, `query_rows_returned: integer`, `query_result_payload_bytes: integer`, `query_applied_filter_version: string`, `query_applied_filter_sha256: string`, `query_applied_filter_count: integer`, `query_exact: boolean`, `ordering_exact: boolean` | +| `SpanObserveListResult` | `metadata:` [`SpanListMetadata`](#spanlistmetadata), `table: any[]`, `config:` [`SpanListColumnConfig`](#spanlistcolumnconfig)[] | +| `TraceDetailResult` | `trace: any`, `observation_spans:` [`TraceDetailSpan`](#tracedetailspan)[], `summary: any`, `graph: any` | +| `TraceDetailSpan` | `observation_span: any`, `children: any[]`, `eval_scores: any[]`, `eval_rollup:` [`EvalRollup`](#evalrollup), `annotations: any[]` | +| `TraceErrorAnalysisResult` | `analysis_exists: boolean`, `trace_id: string`, `message: string`, `analysis_id: string`, `analysis_date: string`, `agent_version: string`, `memory_enhanced: boolean`, `summary: any`, `errors: any[]`, `grouped_errors: any[]`, `scores: any`, `memory_context: any` | +| `TraceObserveColumnConfig` | `id: string`, `name: string`, `is_visible: boolean`, `group_by: string`, `output_type: string`, `reverse_output: boolean`, `annotation_label_type: string`, `choices: string[]`, `settings: any JSON value`, `choices_map: any JSON value`, `eval_template_id: string`, `target_type: string`, `annotators: any JSON value`, `source_field: string`, `parent_eval_id: string`, `property_id: string`, `property_kind: string`, `property_source: string` | +| `TraceObserveListMetadata` | `total_rows: integer`, `total_rows_exact: integer`, `total_rows_is_lower_bound: boolean`, `has_more: boolean`, `next_cursor: string`, `next_cursor_fingerprint: string`, `query_complete: boolean`, `query_status: string`, `query_error_code: string`, `query_elapsed_ms: number`, `query_count: integer`, `query_rows_returned: integer`, `query_result_payload_bytes: integer`, `query_applied_filter_version: string`, `query_applied_filter_sha256: string`, `query_applied_filter_count: integer`, `query_exact: boolean`, `ordering_exact: boolean` | +| `TraceObserveListResult` | `metadata:` [`TraceObserveListMetadata`](#traceobservelistmetadata), `table: any[]`, `config:` [`TraceObserveColumnConfig`](#traceobservecolumnconfig)[] | +| `TracePreview` | `trace_id: string`, `input: string`, `output: string` | +| `TraceSessionDetailResult` | `session_metadata: any`, `response: any[]`, `next: boolean` | +| `TraceSessionListMetadata` | `total_rows: integer`, `total_rows_exact: integer`, `total_rows_is_lower_bound: boolean`, `has_more: boolean`, `next_cursor: string`, `next_cursor_fingerprint: string`, `query_complete: boolean`, `query_status: string`, `query_error_code: string`, `query_elapsed_ms: number`, `query_count: integer`, `query_rows_returned: integer`, `query_result_payload_bytes: integer`, `query_applied_filter_version: string`, `query_applied_filter_sha256: string`, `query_applied_filter_count: integer`, `query_exact: boolean`, `ordering_exact: boolean`, `query_provenance: string` | +| `TraceSessionListResult` | `metadata:` [`TraceSessionListMetadata`](#tracesessionlistmetadata), `table:` [`TraceSessionTableRow`](#tracesessiontablerow)[], `config:` [`TraceObserveColumnConfig`](#traceobservecolumnconfig)[] | +| `TraceSessionTableRow` | `session_id: string`, `session_name: string`, `project_id: string`, `start_time: string`, `end_time: string`, `created_at: string`, `duration: number`, `total_cost: number`, `total_tokens: integer`, `total_traces_count: integer`, `first_message: any JSON value`, `last_message: any JSON value`, `user_id: string`, `user_id_type: string`, `user_id_hash: string` | +| `TrendPoint` | `timestamp: string`, `value: integer`, `users: integer` | +| `User` | `id: string`, `email: string`, `name: string`, `organization_role: string`, `organization:` [`Organization`](#organization), `created_at: string`, `status: any`, `role: string`, `goals: any` | +| `UserAlertMonitorListColumn` | `id: string`, `name: string`, `is_visible: boolean` | +| `UserAlertMonitorListItem` | `id: string`, `name: string`, `created_at: string`, `updated_at: string`, `metric_type: string`, `filters: any`, `status: string`, `no_of_alerts: integer`, `last_triggered: string`, `is_mute: boolean`, `trends:` [`UserAlertMonitorTrend`](#useralertmonitortrend)[] | +| `UserAlertMonitorListMetadata` | `total_rows: integer`, `total_pages: integer` | +| `UserAlertMonitorListResult` | `column_config:` [`UserAlertMonitorListColumn`](#useralertmonitorlistcolumn)[], `table:` [`UserAlertMonitorListItem`](#useralertmonitorlistitem)[], `metadata:` [`UserAlertMonitorListMetadata`](#useralertmonitorlistmetadata) | +| `UserAlertMonitorLog` | `id: string`, `resolved_by:` [`User`](#user), `created_at: string`, `type: string`, `message: string`, `resolved: boolean`, `resolved_at: string`, `link: string`, `time_window_start: string`, `time_window_end: string` | +| `UserAlertMonitorTrend` | `timestamp: string`, `count: integer` | diff --git a/src/pages/docs/sdk/reference/optimizations.mdx b/src/pages/docs/sdk/reference/optimizations.mdx new file mode 100644 index 000000000..50c4223b6 --- /dev/null +++ b/src/pages/docs/sdk/reference/optimizations.mdx @@ -0,0 +1,199 @@ +--- +title: "Optimizations" +description: "Reference for client.optimizations in the Future AGI Python and TypeScript SDKs: optimizations.create, optimizations.get, optimizations.list." +--- + +`client.optimizations` on `fi.Client` (Python) and `client.optimizations` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Datasets & evals response models](/docs/sdk/reference/datasets-evals-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`optimizations.create`](#optimizationscreate) | Create a dataset optimization run. | +| [`optimizations.get`](#optimizationsget) | Return a dataset optimization run by its identifier. | +| [`optimizations.list`](#optimizationslist) | List dataset optimization runs. | + +## client.optimizations + +### optimizations.create + +Create a dataset optimization run. + + + +**MCP tool**: `create_optimization_run` + + + +```python Python +result = client.optimizations.create( + name="your-name", + column_id="your-column-id", + optimizer_algorithm="random_search", +) +``` + +```typescript TypeScript +const result = await client.optimizations.create({ + name: "your-name", + column_id: "your-column-id", + optimizer_algorithm: "random_search", +}); +``` + + + + + +```python Python +client.optimizations.create( + *, + name: str, + column_id: str, + optimizer_algorithm: Literal['random_search', 'bayesian', 'metaprompt', 'protegi', 'promptwizard', 'gepa'], + optimizer_model_id: str | None | NotGiven = NOT_GIVEN, + optimizer_config: dict[str, Any] | None | NotGiven = NOT_GIVEN, + user_eval_template_ids: list[str] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.OptimizationsCreateResult +``` + +```typescript TypeScript +client.optimizations.create(params: OptimizationsCreateParams, options?: RequestOptions): Promise + +export interface OptimizationsCreateParams { + name: string; + column_id: string; + optimizer_algorithm: "random_search" | "bayesian" | "metaprompt" | "protegi" | "promptwizard" | "gepa"; + optimizer_model_id?: string | null; + optimizer_config?: Record | null; + user_eval_template_ids?: Array | null; +} +``` + + + +#### Parameters + + + + + + + + +#### Returns + +[`OptimizationsCreateResult`](/docs/sdk/reference/datasets-evals-models#optimizationscreateresult). + +### optimizations.get + +Return a dataset optimization run by its identifier. + + + +**MCP tool**: `get_optimization_run` + + + +```python Python +result = client.optimizations.get("your-id") +``` + +```typescript TypeScript +const result = await client.optimizations.get("your-id"); +``` + + + + + +```python Python +client.optimizations.get( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DatasetOptimizationDetail +``` + +```typescript TypeScript +client.optimizations.get(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this optimize dataset. + + +#### Returns + +[`DatasetOptimizationDetail`](/docs/sdk/reference/datasets-evals-models#datasetoptimizationdetail). + +### optimizations.list + +List dataset optimization runs. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_optimization_runs` + + + +```python Python +for item in client.optimizations.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.optimizations.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.optimizations.list( + *, + dataset_id: str | None | NotGiven = NOT_GIVEN, + column_id: str | None | NotGiven = NOT_GIVEN, + develop_id: str | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[Any] +``` + +```typescript TypeScript +client.optimizations.list(params: OptimizationsListParams = {}, options?: RequestOptions): Pager + +export interface OptimizationsListParams { + dataset_id?: string | null; + column_id?: string | null; + develop_id?: string | null; + limit?: number | null; +} +``` + + + +#### Parameters + + + + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. diff --git a/src/pages/docs/sdk/reference/projects.mdx b/src/pages/docs/sdk/reference/projects.mdx new file mode 100644 index 000000000..426222285 --- /dev/null +++ b/src/pages/docs/sdk/reference/projects.mdx @@ -0,0 +1,132 @@ +--- +title: "Projects" +description: "Reference for client.projects in the Future AGI Python and TypeScript SDKs: projects.get, projects.list." +--- + +`client.projects` on `fi.Client` (Python) and `client.projects` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Observability response models](/docs/sdk/reference/observability-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`projects.get`](#projectsget) | Return a tracing project by its identifier. | +| [`projects.list`](#projectslist) | List tracing projects available in the current workspace. | + +## client.projects + +### projects.get + +Return a tracing project by its identifier. + + + +**MCP tool**: `get_project` + + + +```python Python +result = client.projects.get("your-id") +``` + +```typescript TypeScript +const result = await client.projects.get("your-id"); +``` + + + + + +```python Python +client.projects.get( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.ProjectDetailResult +``` + +```typescript TypeScript +client.projects.get(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `id`. + + +#### Returns + +[`ProjectDetailResult`](/docs/sdk/reference/observability-models#projectdetailresult). + +### projects.list + +List tracing projects available in the current workspace. + + + +**MCP tool**: `list_projects` + + + +```python Python +result = client.projects.list() +``` + +```typescript TypeScript +const result = await client.projects.list(); +``` + + + + + +```python Python +client.projects.list( + *, + name: str | None | NotGiven = NOT_GIVEN, + project_type: str | None | NotGiven = NOT_GIVEN, + tags: str | None | NotGiven = NOT_GIVEN, + filters: str | None | NotGiven = NOT_GIVEN, + sort_by: str | None | NotGiven = NOT_GIVEN, + sort_direction: Literal['asc', 'desc'] | None | NotGiven = NOT_GIVEN, + page_number: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.projects.list(params: ProjectsListParams = {}, options?: RequestOptions): Promise + +export interface ProjectsListParams { + name?: string | null; + project_type?: string | null; + tags?: string | null; + filters?: string | null; + sort_by?: string | null; + sort_direction?: "asc" | "desc" | null; + page_number?: number | null; + page_size?: number | null; +} +``` + + + +#### Parameters + + + + + + + + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. diff --git a/src/pages/docs/sdk/reference/prompts-models.mdx b/src/pages/docs/sdk/reference/prompts-models.mdx new file mode 100644 index 000000000..af30fdb6a --- /dev/null +++ b/src/pages/docs/sdk/reference/prompts-models.mdx @@ -0,0 +1,17 @@ +--- +title: "Prompts response models" +description: "The 6 response models returned by the prompts resources of the Future AGI Python and TypeScript SDKs, with every field and its type." +--- + +The models returned by `client.prompts`, 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)). + +## Models + +| Model | Fields | +|---|---| +| `PromptHistoryExecution` | `id: string`, `template_version: string`, `output: any`, `prompt_config_snapshot: any`, `template_name: string`, `original_template: string`, `metadata: any`, `variable_names: any`, `evaluation_results: any`, `evaluation_configs: any`, `created_at: string`, `is_default: boolean`, `commit_message: string`, `updated_at: string`, `is_draft: boolean`, `labels: any`, `placeholders: any`, `prompt_base_template: string` | +| `PromptLabel` | `id: string`, `organization: string`, `name: string`, `type: string`, `metadata: any`, `created_at: string`, `updated_at: string` | +| `PromptRunStatusResult` | `status: string`, `error_message: string`, `executions_result:` [`PromptHistoryExecution`](#prompthistoryexecution) | +| `PromptTemplate` | `id: string`, `name: string`, `description: string`, `variable_names: any`, `organization: string`, `prompt_folder: string`, `placeholders: any`, `created_by: string` | +| `PromptTemplatePatch` | `id: string`, `name: string`, `description: string`, `variable_names: any`, `organization: string`, `prompt_folder: string`, `placeholders: any`, `created_by: string` | +| `PromptsRunResult` | `template_id: string`, `prompt_config: any[]`, `variable_names: any`, `evaluation_configs: any[]`, `placeholders: any` | diff --git a/src/pages/docs/sdk/reference/prompts.mdx b/src/pages/docs/sdk/reference/prompts.mdx new file mode 100644 index 000000000..f1f2cfa96 --- /dev/null +++ b/src/pages/docs/sdk/reference/prompts.mdx @@ -0,0 +1,1388 @@ +--- +title: "Prompts" +description: "Reference for client.prompts in the Future AGI Python and TypeScript SDKs: prompts.add_draft, prompts.commit, prompts.create, prompts.create_draft, prompts.delete, prompts.generate and 16 more." +--- + +`client.prompts` on `fi.Client` (Python) and `client.prompts` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.prompts.labels`, `client.prompts.versions`. The models these methods return are on [Prompts response models](/docs/sdk/reference/prompts-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`prompts.add_draft`](#promptsadd_draft) | Add new draft versions to a prompt template. | +| [`prompts.commit`](#promptscommit) | Commit the current draft of a prompt template as a named version, optionally making it the default. | +| [`prompts.create`](#promptscreate) | Create a prompt template in the current workspace. | +| [`prompts.create_draft`](#promptscreate_draft) | Create a prompt template together with its first draft version (messages, model configuration, variables). | +| [`prompts.delete`](#promptsdelete) | Delete a prompt template and all its versions. | +| [`prompts.generate`](#promptsgenerate) | Generate a prompt from a plain-language statement of what it should do. | +| [`prompts.get`](#promptsget) | Open a prompt template by its identifier, creating its workbench draft if needed. | +| [`prompts.get_by_name`](#promptsget_by_name) | Fetch a prompt template by name; the default version unless `version` is given. | +| [`prompts.history`](#promptshistory) | List past prompt executions, optionally for one template. | +| [`prompts.improve`](#promptsimprove) | Rewrite an existing prompt according to the given improvement requirements. | +| [`prompts.list`](#promptslist) | List prompt templates available in the current workspace. | +| [`prompts.run`](#promptsrun) | Run a configured prompt version by supplying version and is_run="prompt". | +| [`prompts.run_status`](#promptsrun_status) | Read workbench prompt execution status and outputs. | +| [`prompts.update`](#promptsupdate) | Update selected fields on an existing prompt template. | +| [`prompts.labels.assign`](#promptslabelsassign) | Assign a label to one version of a prompt template. | +| [`prompts.labels.create`](#promptslabelscreate) | Create a prompt label. | +| [`prompts.labels.for_template`](#promptslabelsfor_template) | List the labels assigned to a prompt template's versions. | +| [`prompts.labels.get_template`](#promptslabelsget_template) | Fetch the prompt template version a label points to, by template name and label (or version). | +| [`prompts.labels.list`](#promptslabelslist) | List prompt labels (e.g. | +| [`prompts.labels.remove`](#promptslabelsremove) | Remove a label from a prompt template version. | +| [`prompts.labels.set_default`](#promptslabelsset_default) | Make a version the default for a prompt template, by template name. | +| [`prompts.versions.list`](#promptsversionslist) | List versions of a prompt template. | + +## client.prompts + +### prompts.add_draft + +Add new draft versions to a prompt template. Each entry carries prompt_config, variable_names, evaluation_configs, metadata and placeholders. + + + + + +```python Python +result = client.prompts.add_draft("your-id", new_prompts=[]) +``` + +```typescript TypeScript +const result = await client.prompts.addDraft("your-id", { new_prompts: [] }); +``` + + + + + +```python Python +client.prompts.add_draft( + id: str, + *, + new_prompts: list[dict[str, Any]], + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.addDraft(id: string, params: PromptsAddDraftParams, options?: RequestOptions): Promise + +export interface PromptsAddDraftParams { + new_prompts: Array>; +} +``` + + + +#### Parameters + + + A UUID string identifying this prompt template. + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### prompts.commit + +Commit the current draft of a prompt template as a named version, optionally making it the default. + + + + + +```python Python +result = client.prompts.commit("your-id", version_name="your-version-name") +``` + +```typescript TypeScript +const result = await client.prompts.commit("your-id", { version_name: "your-version-name" }); +``` + + + + + +```python Python +client.prompts.commit( + id: str, + *, + version_name: str, + message: str | None | NotGiven = NOT_GIVEN, + set_default: bool | None | NotGiven = NOT_GIVEN, + is_draft: bool | None | NotGiven = NOT_GIVEN, + metadata: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.commit(id: string, params: PromptsCommitParams, options?: RequestOptions): Promise + +export interface PromptsCommitParams { + version_name: string; + message?: string | null; + set_default?: boolean | null; + is_draft?: boolean | null; + metadata?: Record | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this prompt template. + + + + + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### prompts.create + +Create a prompt template in the current workspace. + + + +**MCP tool**: `create_prompt_template` + + + +```python Python +result = client.prompts.create(name="your-name") +``` + +```typescript TypeScript +const result = await client.prompts.create({ name: "your-name" }); +``` + + + + + +```python Python +client.prompts.create( + *, + name: str, + description: str | None | NotGiven = NOT_GIVEN, + variable_names: dict[str, Any] | None | NotGiven = NOT_GIVEN, + prompt_folder: str | None | NotGiven = NOT_GIVEN, + placeholders: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.PromptTemplate +``` + +```typescript TypeScript +client.prompts.create(params: PromptsCreateParams, options?: RequestOptions): Promise + +export interface PromptsCreateParams { + name: string; + description?: string | null; + variable_names?: Record | null; + prompt_folder?: string | null; + placeholders?: Record | null; +} +``` + + + +#### Parameters + + + + + + + +#### Returns + +[`PromptTemplate`](/docs/sdk/reference/prompts-models#prompttemplate). + +### prompts.create_draft + +Create a prompt template together with its first draft version (messages, model configuration, variables). + + + + + +```python Python +result = client.prompts.create_draft(name="your-name", prompt_config=[]) +``` + +```typescript TypeScript +const result = await client.prompts.createDraft({ + name: "your-name", + prompt_config: [], +}); +``` + + + + + +```python Python +client.prompts.create_draft( + *, + name: str, + prompt_config: list[dict[str, Any]], + variable_names: dict[str, Any] | None | NotGiven = NOT_GIVEN, + evaluation_configs: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + metadata: dict[str, Any] | None | NotGiven = NOT_GIVEN, + placeholders: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.PromptTemplate +``` + +```typescript TypeScript +client.prompts.createDraft(params: PromptsCreateDraftParams, options?: RequestOptions): Promise + +export interface PromptsCreateDraftParams { + name: string; + prompt_config: Array>; + variable_names?: Record | null; + evaluation_configs?: Array> | null; + metadata?: Record | null; + placeholders?: Record | null; +} +``` + + + +#### Parameters + + + + + + + + +#### Returns + +[`PromptTemplate`](/docs/sdk/reference/prompts-models#prompttemplate). + +### prompts.delete + +Delete a prompt template and all its versions. + + + + + +```python Python +result = client.prompts.delete("your-id") +``` + +```typescript TypeScript +const result = await client.prompts.delete("your-id"); +``` + + + + + +```python Python +client.prompts.delete( + id: str, + *, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.delete(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this prompt template. + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### prompts.generate + +Generate a prompt from a plain-language statement of what it should do. + + + + + +```python Python +result = client.prompts.generate(statement="your-statement") +``` + +```typescript TypeScript +const result = await client.prompts.generate({ statement: "your-statement" }); +``` + + + + + +```python Python +client.prompts.generate( + *, + statement: str, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.generate(params: PromptsGenerateParams, options?: RequestOptions): Promise + +export interface PromptsGenerateParams { + statement: string; +} +``` + + + +#### Parameters + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### prompts.get + +Open a prompt template by its identifier, creating its workbench draft if needed. + + + +**MCP tool**: `get_prompt_template` + + + +```python Python +result = client.prompts.get("your-id") +``` + +```typescript TypeScript +const result = await client.prompts.get("your-id"); +``` + + + + + +```python Python +client.prompts.get( + id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.PromptTemplate +``` + +```typescript TypeScript +client.prompts.get(id: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + A UUID string identifying this prompt template. + + +#### Returns + +[`PromptTemplate`](/docs/sdk/reference/prompts-models#prompttemplate). + +### prompts.get_by_name + +Fetch a prompt template by name; the default version unless `version` is given. + + + + + +```python Python +result = client.prompts.get_by_name() +``` + +```typescript TypeScript +const result = await client.prompts.getByName(); +``` + + + + + +```python Python +client.prompts.get_by_name( + *, + name: str | None | NotGiven = NOT_GIVEN, + version: str | None | NotGiven = NOT_GIVEN, + created_at: str | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + ordering: str | None | NotGiven = NOT_GIVEN, + page: int | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.getByName(params: PromptsGetByNameParams = {}, options?: RequestOptions): Promise + +export interface PromptsGetByNameParams { + name?: string | null; + version?: string | null; + created_at?: string | null; + /** A search term. */ + search?: string | null; + /** Which field to use when ordering the results. */ + ordering?: string | null; + /** A page number within the paginated result set. */ + page?: number | null; + /** Number of results to return per page. */ + limit?: number | null; +} +``` + + + +#### Parameters + + + + + + A search term. + + + Which field to use when ordering the results. + + + A page number within the paginated result set. + + + Number of results to return per page. + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### prompts.history + +List past prompt executions, optionally for one template. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) + + + +```python Python +for item in client.prompts.history(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.prompts.history()) { + console.log(item); +} +``` + + + + + +```python Python +client.prompts.history( + *, + template_name: str | None | NotGiven = NOT_GIVEN, + template_version: str | None | NotGiven = NOT_GIVEN, + created_at: str | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + ordering: str | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + template_id: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.PromptHistoryExecution] +``` + +```typescript TypeScript +client.prompts.history(params: PromptsHistoryParams = {}, options?: RequestOptions): Pager + +export interface PromptsHistoryParams { + template_name?: string | null; + template_version?: string | null; + created_at?: string | null; + /** A search term. */ + search?: string | null; + /** Which field to use when ordering the results. */ + ordering?: string | null; + /** Number of results to return per page. */ + limit?: number | null; + template_id?: string | null; +} +``` + + + +#### Parameters + + + + + + A search term. + + + Which field to use when ordering the results. + + + Number of results to return per page. + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`PromptHistoryExecution`](/docs/sdk/reference/prompts-models#prompthistoryexecution) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### prompts.improve + +Rewrite an existing prompt according to the given improvement requirements. + + + + + +```python Python +result = client.prompts.improve(existing_prompt="your-existing-prompt", improvement_requirements="your-improvement-requirements") +``` + +```typescript TypeScript +const result = await client.prompts.improve({ + existing_prompt: "your-existing-prompt", + improvement_requirements: "your-improvement-requirements", +}); +``` + + + + + +```python Python +client.prompts.improve( + *, + existing_prompt: str, + improvement_requirements: str, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.improve(params: PromptsImproveParams, options?: RequestOptions): Promise + +export interface PromptsImproveParams { + existing_prompt: string; + improvement_requirements: string; +} +``` + + + +#### Parameters + + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### prompts.list + +List prompt templates available in the current workspace. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_prompt_templates` + + + +```python Python +for item in client.prompts.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.prompts.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.prompts.list( + *, + name: str | None | NotGiven = NOT_GIVEN, + version: str | None | NotGiven = NOT_GIVEN, + created_at: str | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + ordering: str | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + modality: list[str] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.PromptTemplate] +``` + +```typescript TypeScript +client.prompts.list(params: PromptsListParams = {}, options?: RequestOptions): Pager + +export interface PromptsListParams { + name?: string | null; + version?: string | null; + created_at?: string | null; + /** A search term. */ + search?: string | null; + /** Which field to use when ordering the results. */ + ordering?: string | null; + /** Number of results to return per page. */ + limit?: number | null; + modality?: Array | null; +} +``` + + + +#### Parameters + + + + + + A search term. + + + Which field to use when ordering the results. + + + Number of results to return per page. + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`PromptTemplate`](/docs/sdk/reference/prompts-models#prompttemplate) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### prompts.run + +Run a configured prompt version by supplying version and is_run="prompt". Optionally replace prompt_config or variable_names. Returns an asynchronous receipt; read get_prompt_run with template_version for status and output. + + + +**MCP tool**: `run_prompt` + + + +```python Python +result = client.prompts.run("your-id") +``` + +```typescript TypeScript +const result = await client.prompts.run("your-id"); +``` + + + + + +```python Python +client.prompts.run( + id: str, + *, + name: str | None | NotGiven = NOT_GIVEN, + version: str | None | NotGiven = NOT_GIVEN, + prompt_config: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + variable_names: dict[str, Any] | None | NotGiven = NOT_GIVEN, + placeholders: Any | None | NotGiven = NOT_GIVEN, + evaluation_configs: list[Any] | None | NotGiven = NOT_GIVEN, + source: str | None | NotGiven = NOT_GIVEN, + is_run: Any | None | NotGiven = NOT_GIVEN, + is_sdk: bool | None | NotGiven = NOT_GIVEN, + run_index: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.PromptsRunResult +``` + +```typescript TypeScript +client.prompts.run(id: string, params: PromptsRunParams = {}, options?: RequestOptions): Promise + +export interface PromptsRunParams { + name?: string | null; + version?: string | null; + prompt_config?: Array> | null; + variable_names?: Record | null; + placeholders?: JsonValue | null; + evaluation_configs?: Array | null; + source?: string | null; + is_run?: JsonValue | null; + is_sdk?: boolean | null; + run_index?: number | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this prompt template. + + + + + + + + + + + + +#### Returns + +[`PromptsRunResult`](/docs/sdk/reference/prompts-models#promptsrunresult). + +### prompts.run_status + +Read workbench prompt execution status and outputs. Supply template_version matching the version returned by run_prompt to read that version, otherwise the API chooses the default/latest version. + + + +**MCP tool**: `get_prompt_run` + + + +```python Python +result = client.prompts.run_status("your-id") +``` + +```typescript TypeScript +const result = await client.prompts.runStatus("your-id"); +``` + + + + + +```python Python +client.prompts.run_status( + id: str, + *, + template_version: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.PromptRunStatusResult +``` + +```typescript TypeScript +client.prompts.runStatus(id: string, params: PromptsRunStatusParams = {}, options?: RequestOptions): Promise + +export interface PromptsRunStatusParams { + template_version?: string | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this prompt template. + + + +#### Returns + +[`PromptRunStatusResult`](/docs/sdk/reference/prompts-models#promptrunstatusresult). + +### prompts.update + +Update selected fields on an existing prompt template. + + + +**MCP tool**: `update_prompt_template` + + + +```python Python +result = client.prompts.update("your-id") +``` + +```typescript TypeScript +const result = await client.prompts.update("your-id"); +``` + + + + + +```python Python +client.prompts.update( + id: str, + *, + name: str | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + variable_names: dict[str, Any] | None | NotGiven = NOT_GIVEN, + prompt_folder: str | None | NotGiven = NOT_GIVEN, + placeholders: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.PromptTemplatePatch +``` + +```typescript TypeScript +client.prompts.update(id: string, params: PromptsUpdateParams = {}, options?: RequestOptions): Promise + +export interface PromptsUpdateParams { + name?: string | null; + description?: string | null; + variable_names?: Record | null; + prompt_folder?: string | null; + placeholders?: Record | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this prompt template. + + + + + + + +#### Returns + +[`PromptTemplatePatch`](/docs/sdk/reference/prompts-models#prompttemplatepatch). + +## client.prompts.labels + +TypeScript: `client.prompts.labels`. + +### prompts.labels.assign + +Assign a label to one version of a prompt template. + + + + + +```python Python +result = client.prompts.labels.assign( + "your-template-id", + "your-label-id", + version="your-version", +) +``` + +```typescript TypeScript +const result = await client.prompts.labels.assign("your-template-id", "your-label-id", { version: "your-version" }); +``` + + + + + +```python Python +client.prompts.labels.assign( + template_id: str, + label_id: str, + *, + version: str, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.labels.assign(templateId: string, labelId: string, params: PromptsLabelsAssignParams, options?: RequestOptions): Promise + +export interface PromptsLabelsAssignParams { + version: string; +} +``` + + + +#### Parameters + + + Positional argument `template_id`. + + + Positional argument `label_id`. + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### prompts.labels.create + +Create a prompt label. + + + + + +```python Python +result = client.prompts.labels.create(name="your-name", type="system") +``` + +```typescript TypeScript +const result = await client.prompts.labels.create({ + name: "your-name", + type: "system", +}); +``` + + + + + +```python Python +client.prompts.labels.create( + *, + name: str, + type: Literal['system', 'custom'], + metadata: dict[str, Any] | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.PromptLabel +``` + +```typescript TypeScript +client.prompts.labels.create(params: PromptsLabelsCreateParams, options?: RequestOptions): Promise + +export interface PromptsLabelsCreateParams { + name: string; + type: "system" | "custom"; + metadata?: Record | null; +} +``` + + + +#### Parameters + + + + + +#### Returns + +[`PromptLabel`](/docs/sdk/reference/prompts-models#promptlabel). + +### prompts.labels.for_template + +List the labels assigned to a prompt template's versions. + + + + + +```python Python +result = client.prompts.labels.for_template() +``` + +```typescript TypeScript +const result = await client.prompts.labels.forTemplate(); +``` + + + + + +```python Python +client.prompts.labels.for_template( + *, + page: int | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + template_id: str | None | NotGiven = NOT_GIVEN, + template_name: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.labels.forTemplate(params: PromptsLabelsForTemplateParams = {}, options?: RequestOptions): Promise + +export interface PromptsLabelsForTemplateParams { + /** A page number within the paginated result set. */ + page?: number | null; + /** Number of results to return per page. */ + limit?: number | null; + template_id?: string | null; + template_name?: string | null; +} +``` + + + +#### Parameters + + + A page number within the paginated result set. + + + Number of results to return per page. + + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### prompts.labels.get_template + +Fetch the prompt template version a label points to, by template name and label (or version). + + + + + +```python Python +result = client.prompts.labels.get_template() +``` + +```typescript TypeScript +const result = await client.prompts.labels.getTemplate(); +``` + + + + + +```python Python +client.prompts.labels.get_template( + *, + page: int | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + name: str | None | NotGiven = NOT_GIVEN, + label: str | None | NotGiven = NOT_GIVEN, + version: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.labels.getTemplate(params: PromptsLabelsGetTemplateParams = {}, options?: RequestOptions): Promise + +export interface PromptsLabelsGetTemplateParams { + /** A page number within the paginated result set. */ + page?: number | null; + /** Number of results to return per page. */ + limit?: number | null; + name?: string | null; + label?: string | null; + version?: string | null; +} +``` + + + +#### Parameters + + + A page number within the paginated result set. + + + Number of results to return per page. + + + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### prompts.labels.list + +List prompt labels (e.g. production, staging) in the organization. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) + + + +```python Python +for item in client.prompts.labels.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.prompts.labels.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.prompts.labels.list( + *, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.PromptLabel] +``` + +```typescript TypeScript +client.prompts.labels.list(params: PromptsLabelsListParams = {}, options?: RequestOptions): Pager + +export interface PromptsLabelsListParams { + /** Number of results to return per page. */ + limit?: number | null; +} +``` + + + +#### Parameters + + + Number of results to return per page. + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`PromptLabel`](/docs/sdk/reference/prompts-models#promptlabel) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### prompts.labels.remove + +Remove a label from a prompt template version. + + + + + +```python Python +result = client.prompts.labels.remove(label_id="your-label-id", version_id="your-version-id") +``` + +```typescript TypeScript +const result = await client.prompts.labels.remove({ + label_id: "your-label-id", + version_id: "your-version-id", +}); +``` + + + + + +```python Python +client.prompts.labels.remove( + *, + label_id: str, + version_id: str, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.labels.remove(params: PromptsLabelsRemoveParams, options?: RequestOptions): Promise + +export interface PromptsLabelsRemoveParams { + label_id: string; + version_id: string; +} +``` + + + +#### Parameters + + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### prompts.labels.set_default + +Make a version the default for a prompt template, by template name. + + + + + +```python Python +result = client.prompts.labels.set_default(template_name="your-template-name", version="your-version") +``` + +```typescript TypeScript +const result = await client.prompts.labels.setDefault({ + template_name: "your-template-name", + version: "your-version", +}); +``` + + + + + +```python Python +client.prompts.labels.set_default( + *, + template_name: str, + version: str, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.prompts.labels.setDefault(params: PromptsLabelsSetDefaultParams, options?: RequestOptions): Promise + +export interface PromptsLabelsSetDefaultParams { + template_name: string; + version: string; +} +``` + + + +#### Parameters + + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +## client.prompts.versions + +TypeScript: `client.prompts.versions`. + +### prompts.versions.list + +List versions of a prompt template. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_prompt_versions` + + + +```python Python +for item in client.prompts.versions.list("your-id"): + print(item) +``` + +```typescript TypeScript +for await (const item of client.prompts.versions.list("your-id")) { + console.log(item); +} +``` + + + + + +```python Python +client.prompts.versions.list( + id: str, + *, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[Any] +``` + +```typescript TypeScript +client.prompts.versions.list(id: string, params: PromptsVersionsListParams = {}, options?: RequestOptions): Pager + +export interface PromptsVersionsListParams { + limit?: number | null; +} +``` + + + +#### Parameters + + + A UUID string identifying this prompt template. + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. diff --git a/src/pages/docs/sdk/reference/provider-keys.mdx b/src/pages/docs/sdk/reference/provider-keys.mdx new file mode 100644 index 000000000..604b6a2ff --- /dev/null +++ b/src/pages/docs/sdk/reference/provider-keys.mdx @@ -0,0 +1,71 @@ +--- +title: "Provider keys" +description: "Reference for client.provider_keys in the Future AGI Python and TypeScript SDKs: provider_keys.list." +--- + +`client.provider_keys` on `fi.Client` (Python) and `client.providerKeys` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Gateway response models](/docs/sdk/reference/gateway-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`provider_keys.list`](#provider_keyslist) | List the model-provider API keys configured for the organization (values are masked). | + +## client.provider_keys + +### provider_keys.list + +List the model-provider API keys configured for the organization (values are masked). + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) + + + +```python Python +for item in client.provider_keys.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.providerKeys.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.provider_keys.list( + *, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.ApiKeyResponse] +``` + +```typescript TypeScript +client.providerKeys.list(params: ProviderKeysListParams = {}, options?: RequestOptions): Pager + +export interface ProviderKeysListParams { + /** Number of results to return per page. */ + limit?: number | null; +} +``` + + + +#### Parameters + + + Number of results to return per page. + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`ApiKeyResponse`](/docs/sdk/reference/gateway-models#apikeyresponse) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). diff --git a/src/pages/docs/sdk/reference/scores.mdx b/src/pages/docs/sdk/reference/scores.mdx new file mode 100644 index 000000000..c1eefb883 --- /dev/null +++ b/src/pages/docs/sdk/reference/scores.mdx @@ -0,0 +1,240 @@ +--- +title: "Scores" +description: "Reference for client.scores in the Future AGI Python and TypeScript SDKs: scores.create, scores.create_bulk, scores.list_for_source." +--- + +`client.scores` on `fi.Client` (Python) and `client.scores` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Annotation response models](/docs/sdk/reference/annotation-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`scores.create`](#scorescreate) | Record one score (annotation value) against a source such as a span or dataset row. | +| [`scores.create_bulk`](#scorescreate_bulk) | Record several scores against one source in a single call. | +| [`scores.list_for_source`](#scoreslist_for_source) | List the scores recorded against one source. | + +## client.scores + +### scores.create + +Record one score (annotation value) against a source such as a span or dataset row. + + + + + +```python Python +result = client.scores.create( + source_type="dataset_row", + source_id="your-source-id", + label_id="your-label-id", + value="your-value", +) +``` + +```typescript TypeScript +const result = await client.scores.create({ + source_type: "dataset_row", + source_id: "your-source-id", + label_id: "your-label-id", + value: "your-value", +}); +``` + + + + + +```python Python +client.scores.create( + *, + source_type: Literal['dataset_row', 'trace', 'observation_span', 'prototype_run', 'call_execution', 'trace_session'], + source_id: str, + label_id: str, + value: Any, + notes: str | None | NotGiven = NOT_GIVEN, + score_source: Literal['human', 'api', 'auto', 'imported'] | None | NotGiven = NOT_GIVEN, + queue_item_id: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.Score +``` + +```typescript TypeScript +client.scores.create(params: ScoresCreateParams, options?: RequestOptions): Promise + +export interface ScoresCreateParams { + source_type: "dataset_row" | "trace" | "observation_span" | "prototype_run" | "call_execution" | "trace_session"; + source_id: string; + label_id: string; + value: JsonValue; + notes?: string | null; + score_source?: "human" | "api" | "auto" | "imported" | null; + queue_item_id?: string | null; +} +``` + + + +#### Parameters + + + + + + + + + +#### Returns + +[`Score`](/docs/sdk/reference/annotation-models#score). + +### scores.create_bulk + +Record several scores against one source in a single call. + + + + + +```python Python +result = client.scores.create_bulk( + source_type="dataset_row", + source_id="your-source-id", + scores=[], +) +``` + +```typescript TypeScript +const result = await client.scores.createBulk({ + source_type: "dataset_row", + source_id: "your-source-id", + scores: [], +}); +``` + + + + + +```python Python +client.scores.create_bulk( + *, + source_type: Literal['dataset_row', 'trace', 'observation_span', 'prototype_run', 'call_execution', 'trace_session'], + source_id: str, + scores: list[dict[str, Any]], + notes: str | None | NotGiven = NOT_GIVEN, + span_notes: str | None | NotGiven = NOT_GIVEN, + span_notes_source_id: str | None | NotGiven = NOT_GIVEN, + queue_item_id: str | None | NotGiven = NOT_GIVEN, + project_id: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.BulkCreateScoresResult +``` + +```typescript TypeScript +client.scores.createBulk(params: ScoresCreateBulkParams, options?: RequestOptions): Promise + +export interface ScoresCreateBulkParams { + source_type: "dataset_row" | "trace" | "observation_span" | "prototype_run" | "call_execution" | "trace_session"; + source_id: string; + scores: Array>; + notes?: string | null; + span_notes?: string | null; + span_notes_source_id?: string | null; + queue_item_id?: string | null; + project_id?: string | null; +} +``` + + + +#### Parameters + + + + + + + + + + +#### Returns + +[`BulkCreateScoresResult`](/docs/sdk/reference/annotation-models#bulkcreatescoresresult). + +### scores.list_for_source + +List the scores recorded against one source. + + + + + +```python Python +result = client.scores.list_for_source(source_type="dataset_row", source_id="your-source-id") +``` + +```typescript TypeScript +const result = await client.scores.listForSource({ + source_type: "dataset_row", + source_id: "your-source-id", +}); +``` + + + + + +```python Python +client.scores.list_for_source( + *, + source_type: Literal['dataset_row', 'trace', 'observation_span', 'prototype_run', 'call_execution', 'trace_session'], + source_id: str, + page: int | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + project_id: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> List[models.Score] +``` + +```typescript TypeScript +client.scores.listForSource(params: ScoresListForSourceParams, options?: RequestOptions): Promise> + +export interface ScoresListForSourceParams { + source_type: "dataset_row" | "trace" | "observation_span" | "prototype_run" | "call_execution" | "trace_session"; + source_id: string; + /** A page number within the paginated result set. */ + page?: number | null; + /** Number of results to return per page. */ + limit?: number | null; + /** Tracer project the trace / span was opened from. The same id can exist in several projects; when supplied, only that project's scores are listed. */ + project_id?: string | null; +} +``` + + + +#### Parameters + + + + + A page number within the paginated result set. + + + Number of results to return per page. + + + Tracer project the trace / span was opened from. The same id can exist in several projects; when supplied, only that project's scores are listed. + + +#### Returns + +A list of [`Score`](/docs/sdk/reference/annotation-models#score). diff --git a/src/pages/docs/sdk/reference/sessions.mdx b/src/pages/docs/sdk/reference/sessions.mdx new file mode 100644 index 000000000..6bd7c73f6 --- /dev/null +++ b/src/pages/docs/sdk/reference/sessions.mdx @@ -0,0 +1,171 @@ +--- +title: "Sessions" +description: "Reference for client.sessions in the Future AGI Python and TypeScript SDKs: sessions.get, sessions.list." +--- + +`client.sessions` on `fi.Client` (Python) and `client.sessions` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Observability response models](/docs/sdk/reference/observability-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`sessions.get`](#sessionsget) | Return a trace session by its identifier. | +| [`sessions.list`](#sessionslist) | List trace sessions using the supplied filters. | + +## client.sessions + +### sessions.get + +Return a trace session by its identifier. + + + +**MCP tool**: `get_session` + + + +```python Python +result = client.sessions.get("your-id") +``` + +```typescript TypeScript +const result = await client.sessions.get("your-id"); +``` + + + + + +```python Python +client.sessions.get( + id: str, + *, + navigation_context: str | None | NotGiven = NOT_GIVEN, + user_id: str | None | NotGiven = NOT_GIVEN, + filters: str | None | NotGiven = NOT_GIVEN, + sort_params: str | None | NotGiven = NOT_GIVEN, + page_number: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.TraceSessionDetailResult +``` + +```typescript TypeScript +client.sessions.get(id: string, params: SessionsGetParams = {}, options?: RequestOptions): Promise + +export interface SessionsGetParams { + navigation_context?: string | null; + user_id?: string | null; + filters?: string | null; + sort_params?: string | null; + page_number?: number | null; + page_size?: number | null; +} +``` + + + +#### Parameters + + + Positional argument `id`. + + + + + + + + +#### Returns + +[`TraceSessionDetailResult`](/docs/sdk/reference/observability-models#tracesessiondetailresult). + +### sessions.list + +List trace sessions using the supplied filters. + + + +**MCP tool**: `list_sessions` + + + +```python Python +result = client.sessions.list() +``` + +```typescript TypeScript +const result = await client.sessions.list(); +``` + + + + + +```python Python +client.sessions.list( + *, + project_id: str | None | NotGiven = NOT_GIVEN, + user_id: str | None | NotGiven = NOT_GIVEN, + bookmarked: bool | None | NotGiven = NOT_GIVEN, + filters: str | None | NotGiven = NOT_GIVEN, + sort_params: str | None | NotGiven = NOT_GIVEN, + page_number: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + cursor: str | None | NotGiven = NOT_GIVEN, + cursor_mode: bool | None | NotGiven = NOT_GIVEN, + interval: str | None | NotGiven = NOT_GIVEN, + allow_sampled: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.TraceSessionListResult +``` + +```typescript TypeScript +client.sessions.list(params: SessionsListParams = {}, options?: RequestOptions): Promise + +export interface SessionsListParams { + project_id?: string | null; + user_id?: string | null; + bookmarked?: boolean | null; + filters?: string | null; + sort_params?: string | null; + /** Zero-based numbered page. Pages whose required ordered work exceeds the finite read contract return HTTP 422 with code page_depth_exceeded; request an earlier page or narrow the time range. */ + page_number?: number | null; + page_size?: number | null; + /** Opaque continuation token returned by the previous page. When supplied, do not also send the numbered-page parameter. */ + cursor?: string | null; + cursor_mode?: boolean | null; + interval?: string | null; + /** Omit for backward-compatible complete bounded pages, which may label total_rows as a lower bound. Send false to require an exact total, or true to opt in explicitly to lower-bound totals. */ + allow_sampled?: boolean | null; +} +``` + + + +#### Parameters + + + + + + + + Zero-based numbered page. Pages whose required ordered work exceeds the finite read contract return HTTP 422 with code page_depth_exceeded; request an earlier page or narrow the time range. + + + + Opaque continuation token returned by the previous page. When supplied, do not also send the numbered-page parameter. + + + + + Omit for backward-compatible complete bounded pages, which may label total_rows as a lower bound. Send false to require an exact total, or true to opt in explicitly to lower-bound totals. + + +#### Returns + +[`TraceSessionListResult`](/docs/sdk/reference/observability-models#tracesessionlistresult). diff --git a/src/pages/docs/sdk/reference/simulation-models.mdx b/src/pages/docs/sdk/reference/simulation-models.mdx new file mode 100644 index 000000000..217b254db --- /dev/null +++ b/src/pages/docs/sdk/reference/simulation-models.mdx @@ -0,0 +1,31 @@ +--- +title: "Simulation response models" +description: "The 20 response models returned by the simulation resources of the Future AGI Python and TypeScript SDKs, with every field and its type." +--- + +The models returned by `client.agents`, `client.simulation`, 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)). + +## Models + +| Model | Fields | +|---|---| +| `AgentDefinitionCreateResponse` | `message: string`, `agent:` [`AgentDefinitionResponse`](#agentdefinitionresponse) | +| `AgentDefinitionDetailResponse` | `id: string`, `agent_name: string`, `agent_type: string`, `contact_number: string`, `inbound: boolean`, `target_speaks_first: boolean`, `description: string`, `assistant_id: string`, `provider: string`, `language: string`, `languages: string[]`, `authentication_method: string`, `websocket_url: string`, `websocket_headers: any`, `workspace: string`, `knowledge_base: string`, `organization: string`, `api_key: any`, `observability_provider: string`, `created_at: string`, `updated_at: string`, `model: string`, `model_details: any`, `livekit_url: any`, `livekit_api_key: any`, `livekit_agent_name: any`, `livekit_config_json: any`, `livekit_max_concurrency: any`, `versions: any`, `active_version: any`, `version_count: integer`, `agent_kind: string`, `source: string`, `environment_count: integer`, `observability_enabled: boolean` | +| `AgentDefinitionEditResponse` | `message: string`, `agent:` [`AgentDefinitionResponse`](#agentdefinitionresponse) | +| `AgentDefinitionListResponse` | `id: string`, `agent_name: string`, `agent_type: string`, `contact_number: string`, `inbound: boolean`, `target_speaks_first: boolean`, `description: string`, `assistant_id: string`, `provider: string`, `language: string`, `languages: string[]`, `websocket_url: string`, `websocket_headers: any`, `workspace: string`, `knowledge_base: string`, `organization: string`, `created_at: string`, `updated_at: string`, `latest_version: any`, `latest_version_id: any`, `model_details: any`, `model: string`, `agent_kind: string`, `source: string`, `version_count: integer`, `environment_count: integer`, `environments:` [`RunEnvironmentRef`](#runenvironmentref)[] | +| `AgentDefinitionResponse` | `id: string`, `agent_name: string`, `agent_type: string`, `contact_number: string`, `inbound: boolean`, `target_speaks_first: boolean`, `description: string`, `assistant_id: string`, `provider: string`, `language: string`, `languages: string[]`, `authentication_method: string`, `websocket_url: string`, `websocket_headers: any`, `workspace: string`, `knowledge_base: string`, `organization: string`, `api_key: any`, `observability_provider: string`, `created_at: string`, `updated_at: string`, `model: string`, `model_details: any`, `livekit_url: any`, `livekit_api_key: any`, `livekit_agent_name: any`, `livekit_config_json: any`, `livekit_max_concurrency: any` | +| `AgentVersionCreateResponse` | `message: string`, `version:` [`AgentVersionResponse`](#agentversionresponse) | +| `AgentVersionResponse` | `id: string`, `version_number: integer`, `version_name: string`, `version_name_display: any`, `status: string`, `status_display: string`, `score: string`, `test_count: integer`, `pass_rate: string`, `description: string`, `commit_message: string`, `release_notes: string`, `agent_definition: string`, `organization: string`, `configuration_snapshot: any`, `is_active: any`, `is_latest: any`, `agent_kind: string`, `api_key: string`, `created_at: string`, `updated_at: string` | +| `CallExecution` | `id: string`, `phone_number: string`, `service_provider_call_id: string`, `status: string`, `started_at: string`, `completed_at: string`, `duration_seconds: integer`, `recording_url: string`, `cost_cents: integer`, `call_metadata: any`, `error_message: string`, `scenario_name: string`, `transcripts: any`, `created_at: string`, `updated_at: string`, `provider_call_data: any`, `stereo_recording_url: string`, `ended_reason: string`, `stt_cost_cents: integer`, `llm_cost_cents: integer`, `tts_cost_cents: integer`, `overall_score: number`, `response_time_ms: integer`, `response_time_seconds: any`, `assistant_id: string`, `customer_number: string`, `call_type: string`, `ended_at: string`, `analysis_data: any`, `evaluation_data: any`, `message_count: integer`, `transcript_available: boolean`, `recording_available: boolean`, `eval_outputs: any`, `error_localizer_tasks:` [`CallExecutionErrorLocalizerTask`](#callexecutionerrorlocalizertask)[], `call_summary: string`, `agent_version: string`, `customer_cost_cents: integer`, `system_metrics: any`, `cost_breakdown: any`, `customer_call_id: string`, `simulation_call_type: string`, `processing_skipped: any`, `processing_skip_reason: any` | +| `CallExecutionErrorLocalizerTask` | `task_id: string`, `eval_config_id: string`, `status: string`, `eval_result: any`, `eval_explanation: string`, `input_data: any`, `input_keys: string[]`, `input_types: any`, `rule_prompt: string`, `error_analysis: any`, `selected_input_key: string`, `error_message: string`, `created_at: string`, `updated_at: string` | +| `DatasetColumnConfigEntry` | `name: string`, `type: string` | +| `RunEnvironmentRef` | `id: string`, `name: string` | +| `RunTestExecutionResponse` | `message: string`, `execution_id: string`, `run_test_id: string`, `status: string`, `total_scenarios: integer`, `total_calls: integer`, `scenario_ids: string[]` | +| `RunTestResponse` | `id: string`, `name: string`, `description: any`, `agent_definition: string`, `agent_version: any`, `agent_definition_detail: any`, `source_type: string`, `source_type_display: string`, `prompt_template: string`, `prompt_template_detail: any`, `prompt_version: string`, `prompt_version_detail: any`, `scenarios: string[]`, `scenarios_detail: any[]`, `dataset_row_ids: string[]`, `simulator_agent: string`, `simulator_agent_detail: any`, `simulate_eval_configs: string[]`, `simulate_eval_configs_detail:` [`SimulateEvalConfigResponse`](#simulateevalconfigresponse)[], `evals_detail:` [`SimulateEvalConfigResponse`](#simulateevalconfigresponse)[], `organization: string`, `enable_tool_evaluation: boolean`, `created_at: string`, `updated_at: string`, `last_run_at: string`, `deleted: boolean`, `deleted_at: string` | +| `ScenarioDetailResponse` | `id: string`, `name: string`, `description: string`, `source: string`, `scenario_type: string`, `dataset_id: string`, `organization: string`, `dataset: string`, `created_at: string`, `updated_at: string`, `deleted: boolean`, `deleted_at: string`, `status: string`, `agent_type: string`, `graph: any`, `prompts:` [`ScenarioPromptItem`](#scenariopromptitem)[], `dataset_rows: integer`, `dataset_column_config: any` | +| `ScenarioEditResponse` | `message: string`, `scenario:` [`ScenarioResponse`](#scenarioresponse) | +| `ScenarioPromptItem` | `role: string`, `content: string` | +| `ScenarioResponse` | `id: string`, `name: string`, `description: string`, `source: string`, `scenario_type: string`, `scenario_type_display: string`, `source_type: string`, `source_type_display: string`, `organization: string`, `dataset: string`, `dataset_rows: any`, `dataset_column_config: any`, `graph: any`, `agent: any`, `prompt_template: string`, `prompt_template_detail: any`, `prompt_version: string`, `prompt_version_detail: any`, `created_at: string`, `updated_at: string`, `deleted: boolean`, `status: string`, `deleted_at: string`, `agent_type: any` | +| `SimulateEvalConfigResponse` | `id: string`, `name: string`, `config: any`, `mapping: any`, `filters: object[]`, `error_localizer: boolean`, `model: string`, `status: string`, `eval_group: string`, `template_id: string`, `eval_type: string`, `regradable: boolean`, `editable: boolean` | +| `TestExecution` | `id: string`, `run_test: string`, `run_test_name: string`, `agent_definition_name: string`, `status: string`, `error_reason: string`, `started_at: string`, `completed_at: string`, `total_scenarios: integer`, `total_calls: integer`, `completed_calls: integer`, `failed_calls: integer`, `execution_metadata: any`, `duration_seconds: any`, `success_rate: any`, `calls:` [`CallExecution`](#callexecution)[], `created_at: string`, `scenario_ids: any`, `simulator_agent_name: string`, `simulator_agent_id: string`, `agent_definition_used_name: string`, `agent_definition_used_id: string`, `calls_attempted: any`, `calls_connected_percentage: any` | +| `TestExecutionAnalytics` | `fail_rate_over_test_runs: any`, `evaluation_categories_over_test_runs: any`, `metadata: any` | diff --git a/src/pages/docs/sdk/reference/simulation.mdx b/src/pages/docs/sdk/reference/simulation.mdx new file mode 100644 index 000000000..da174dbce --- /dev/null +++ b/src/pages/docs/sdk/reference/simulation.mdx @@ -0,0 +1,781 @@ +--- +title: "Simulation" +description: "Reference for client.simulation in the Future AGI Python and TypeScript SDKs: simulation.executions.analytics, simulation.executions.get, simulation.executions.list, simulation.scenarios.create, simulation.scenarios.get, simulation.scenarios.list and 5 more." +--- + +`client.simulation` on `fi.Client` (Python) and `client.simulation` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.simulation.executions`, `client.simulation.scenarios`, `client.simulation.tests`. The models these methods return are on [Simulation response models](/docs/sdk/reference/simulation-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`simulation.executions.analytics`](#simulationexecutionsanalytics) | Return aggregated analytics for a simulation test execution. | +| [`simulation.executions.get`](#simulationexecutionsget) | Return a simulation test execution by its identifier. | +| [`simulation.executions.list`](#simulationexecutionslist) | List simulation test executions. | +| [`simulation.scenarios.create`](#simulationscenarioscreate) | Create an agent or prompt simulation scenario of kind dataset, script or graph. | +| [`simulation.scenarios.get`](#simulationscenariosget) | Return a simulation scenario by its identifier. | +| [`simulation.scenarios.list`](#simulationscenarioslist) | List simulation scenarios in the current workspace. | +| [`simulation.scenarios.update`](#simulationscenariosupdate) | Edit supported scenario fields such as name, description, graph or prompt. | +| [`simulation.tests.create`](#simulationtestscreate) | Save a simulation test using name, agent_definition_id and scenario_ids, optionally agent_version and evaluations_config. | +| [`simulation.tests.get`](#simulationtestsget) | Read a saved simulation test configuration, its agent/version and scenarios. | +| [`simulation.tests.list`](#simulationtestslist) | List saved simulation test configurations. | +| [`simulation.tests.run`](#simulationtestsrun) | Start a saved simulation test asynchronously. | + +## client.simulation + +## client.simulation.executions + +TypeScript: `client.simulation.executions`. + +### simulation.executions.analytics + +Return aggregated analytics for a simulation test execution. + + + +**MCP tool**: `get_test_execution_analytics` + + + +```python Python +result = client.simulation.executions.analytics("your-test-execution-id") +``` + +```typescript TypeScript +const result = await client.simulation.executions.analytics("your-test-execution-id"); +``` + + + + + +```python Python +client.simulation.executions.analytics( + test_execution_id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.TestExecutionAnalytics +``` + +```typescript TypeScript +client.simulation.executions.analytics(testExecutionId: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `test_execution_id`. + + +#### Returns + +[`TestExecutionAnalytics`](/docs/sdk/reference/simulation-models#testexecutionanalytics). + +### simulation.executions.get + +Return a simulation test execution by its identifier. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `get_test_execution` + + + +```python Python +for item in client.simulation.executions.get("your-test-execution-id"): + print(item) +``` + +```typescript TypeScript +for await (const item of client.simulation.executions.get("your-test-execution-id")) { + console.log(item); +} +``` + + + + + +```python Python +client.simulation.executions.get( + test_execution_id: str, + *, + search: str | None | NotGiven = NOT_GIVEN, + filters: str | None | NotGiven = NOT_GIVEN, + row_groups: str | None | NotGiven = NOT_GIVEN, + group_keys: str | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[Any] +``` + +```typescript TypeScript +client.simulation.executions.get(testExecutionId: string, params: SimulationExecutionsGetParams = {}, options?: RequestOptions): Pager + +export interface SimulationExecutionsGetParams { + search?: string | null; + filters?: string | null; + row_groups?: string | null; + group_keys?: string | null; + limit?: number | null; +} +``` + + + +#### Parameters + + + Positional argument `test_execution_id`. + + + + + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of `any` items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### simulation.executions.list + +List simulation test executions. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_test_executions` + + + +```python Python +for item in client.simulation.executions.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.simulation.executions.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.simulation.executions.list( + *, + search: str | None | NotGiven = NOT_GIVEN, + status: str | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.TestExecution] +``` + +```typescript TypeScript +client.simulation.executions.list(params: SimulationExecutionsListParams = {}, options?: RequestOptions): Pager + +export interface SimulationExecutionsListParams { + search?: string | null; + status?: string | null; + limit?: number | null; +} +``` + + + +#### Parameters + + + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`TestExecution`](/docs/sdk/reference/simulation-models#testexecution) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +## client.simulation.scenarios + +TypeScript: `client.simulation.scenarios`. + +### simulation.scenarios.create + +Create an agent or prompt simulation scenario of kind dataset, script or graph. Generation is asynchronous and may incur usage charges; poll get_scenario until ready before running tests. Requires the applicable plan entitlement. + + + +**MCP tool**: `create_scenario` + + + +```python Python +result = client.simulation.scenarios.create(name="your-name") +``` + +```typescript TypeScript +const result = await client.simulation.scenarios.create({ name: "your-name" }); +``` + + + + + +```python Python +client.simulation.scenarios.create( + *, + name: str, + description: str | None | NotGiven = NOT_GIVEN, + dataset_id: str | None | NotGiven = NOT_GIVEN, + kind: Literal['graph', 'script', 'dataset'] | None | NotGiven = NOT_GIVEN, + script_url: str | None | NotGiven = NOT_GIVEN, + agent_definition_id: str | None | NotGiven = NOT_GIVEN, + agent_definition_version_id: str | None | NotGiven = NOT_GIVEN, + custom_instruction: str | None | NotGiven = NOT_GIVEN, + no_of_rows: int | None | NotGiven = NOT_GIVEN, + generate_graph: bool | None | NotGiven = NOT_GIVEN, + graph: dict[str, Any] | None | NotGiven = NOT_GIVEN, + source_type: Literal['agent_definition', 'prompt'] | None | NotGiven = NOT_GIVEN, + prompt_template_id: str | None | NotGiven = NOT_GIVEN, + prompt_version_id: str | None | NotGiven = NOT_GIVEN, + add_persona_automatically: bool | None | NotGiven = NOT_GIVEN, + personas: list[str] | None | NotGiven = NOT_GIVEN, + custom_columns: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + agent_name: str | None | NotGiven = NOT_GIVEN, + agent_prompt: str | None | NotGiven = NOT_GIVEN, + voice_provider: str | None | NotGiven = NOT_GIVEN, + voice_name: str | None | NotGiven = NOT_GIVEN, + model: str | None | NotGiven = NOT_GIVEN, + llm_temperature: float | None | NotGiven = NOT_GIVEN, + initial_message: str | None | NotGiven = NOT_GIVEN, + max_call_duration_in_minutes: int | None | NotGiven = NOT_GIVEN, + interrupt_sensitivity: float | None | NotGiven = NOT_GIVEN, + conversation_speed: float | None | NotGiven = NOT_GIVEN, + finished_speaking_sensitivity: float | None | NotGiven = NOT_GIVEN, + initial_message_delay: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> Any +``` + +```typescript TypeScript +client.simulation.scenarios.create(params: SimulationScenariosCreateParams, options?: RequestOptions): Promise + +export interface SimulationScenariosCreateParams { + name: string; + description?: string | null; + dataset_id?: string | null; + kind?: "graph" | "script" | "dataset" | null; + script_url?: string | null; + agent_definition_id?: string | null; + agent_definition_version_id?: string | null; + custom_instruction?: string | null; + no_of_rows?: number | null; + generate_graph?: boolean | null; + graph?: Record | null; + source_type?: "agent_definition" | "prompt" | null; + prompt_template_id?: string | null; + prompt_version_id?: string | null; + add_persona_automatically?: boolean | null; + personas?: Array | null; + custom_columns?: Array> | null; + agent_name?: string | null; + agent_prompt?: string | null; + voice_provider?: string | null; + voice_name?: string | null; + model?: string | null; + llm_temperature?: number | null; + initial_message?: string | null; + max_call_duration_in_minutes?: number | null; + interrupt_sensitivity?: number | null; + conversation_speed?: number | null; + finished_speaking_sensitivity?: number | null; + initial_message_delay?: number | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +#### Returns + +The decoded response. The contract does not describe its shape, so it is untyped. + +### simulation.scenarios.get + +Return a simulation scenario by its identifier. + + + +**MCP tool**: `get_scenario` + + + +```python Python +result = client.simulation.scenarios.get("your-scenario-id") +``` + +```typescript TypeScript +const result = await client.simulation.scenarios.get("your-scenario-id"); +``` + + + + + +```python Python +client.simulation.scenarios.get( + scenario_id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.ScenarioDetailResponse +``` + +```typescript TypeScript +client.simulation.scenarios.get(scenarioId: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `scenario_id`. + + +#### Returns + +[`ScenarioDetailResponse`](/docs/sdk/reference/simulation-models#scenariodetailresponse). + +### simulation.scenarios.list + +List simulation scenarios in the current workspace. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_scenarios` + + + +```python Python +for item in client.simulation.scenarios.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.simulation.scenarios.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.simulation.scenarios.list( + *, + search: str | None | NotGiven = NOT_GIVEN, + agent_definition_id: str | None | NotGiven = NOT_GIVEN, + agent_type: str | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.ScenarioResponse] +``` + +```typescript TypeScript +client.simulation.scenarios.list(params: SimulationScenariosListParams = {}, options?: RequestOptions): Pager + +export interface SimulationScenariosListParams { + search?: string | null; + agent_definition_id?: string | null; + agent_type?: string | null; + limit?: number | null; +} +``` + + + +#### Parameters + + + + + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`ScenarioResponse`](/docs/sdk/reference/simulation-models#scenarioresponse) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### simulation.scenarios.update + +Edit supported scenario fields such as name, description, graph or prompt. This is not a dataset-row editor or a simulation execution. + + + +**MCP tool**: `update_scenario` + + + +```python Python +result = client.simulation.scenarios.update("your-scenario-id") +``` + +```typescript TypeScript +const result = await client.simulation.scenarios.update("your-scenario-id"); +``` + + + + + +```python Python +client.simulation.scenarios.update( + scenario_id: str, + *, + name: str | None | NotGiven = NOT_GIVEN, + description: str | None | NotGiven = NOT_GIVEN, + graph: dict[str, Any] | None | NotGiven = NOT_GIVEN, + prompt: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.ScenarioEditResponse +``` + +```typescript TypeScript +client.simulation.scenarios.update(scenarioId: string, params: SimulationScenariosUpdateParams = {}, options?: RequestOptions): Promise + +export interface SimulationScenariosUpdateParams { + name?: string | null; + description?: string | null; + graph?: Record | null; + prompt?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `scenario_id`. + + + + + + +#### Returns + +[`ScenarioEditResponse`](/docs/sdk/reference/simulation-models#scenarioeditresponse). + +## client.simulation.tests + +TypeScript: `client.simulation.tests`. + +### simulation.tests.create + +Save a simulation test using name, agent_definition_id and scenario_ids, optionally agent_version and evaluations_config. Does not execute it; pass the returned test ID to run_simulation. + + + +**MCP tool**: `create_simulation_test` + + + +```python Python +result = client.simulation.tests.create( + name="your-name", + agent_definition_id="your-agent-definition-id", + scenario_ids=[], +) +``` + +```typescript TypeScript +const result = await client.simulation.tests.create({ + name: "your-name", + agent_definition_id: "your-agent-definition-id", + scenario_ids: [], +}); +``` + + + + + +```python Python +client.simulation.tests.create( + *, + name: str, + agent_definition_id: str, + scenario_ids: list[str], + description: str | None | NotGiven = NOT_GIVEN, + dataset_row_ids: list[str] | None | NotGiven = NOT_GIVEN, + eval_config_ids: list[str] | None | NotGiven = NOT_GIVEN, + evaluations_config: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN, + enable_tool_evaluation: bool | None | NotGiven = NOT_GIVEN, + replay_session_id: str | None | NotGiven = NOT_GIVEN, + agent_version: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.RunTestResponse +``` + +```typescript TypeScript +client.simulation.tests.create(params: SimulationTestsCreateParams, options?: RequestOptions): Promise + +export interface SimulationTestsCreateParams { + name: string; + agent_definition_id: string; + scenario_ids: Array; + description?: string | null; + dataset_row_ids?: Array | null; + eval_config_ids?: Array | null; + evaluations_config?: Array> | null; + enable_tool_evaluation?: boolean | null; + replay_session_id?: string | null; + agent_version?: string | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + +#### Returns + +[`RunTestResponse`](/docs/sdk/reference/simulation-models#runtestresponse). + +### simulation.tests.get + +Read a saved simulation test configuration, its agent/version and scenarios. + + + +**MCP tool**: `get_simulation_test` + + + +```python Python +result = client.simulation.tests.get("your-run-test-id") +``` + +```typescript TypeScript +const result = await client.simulation.tests.get("your-run-test-id"); +``` + + + + + +```python Python +client.simulation.tests.get( + run_test_id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.RunTestResponse +``` + +```typescript TypeScript +client.simulation.tests.get(runTestId: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `run_test_id`. + + +#### Returns + +[`RunTestResponse`](/docs/sdk/reference/simulation-models#runtestresponse). + +### simulation.tests.list + +List saved simulation test configurations. A test configuration is distinct from its executions; use list_test_executions to inspect runs. + + + +**Paginated**: returns a pager ([how pagination works](/docs/sdk/reference#pagination)) · **MCP tool**: `list_simulation_tests` + + + +```python Python +for item in client.simulation.tests.list(): + print(item) +``` + +```typescript TypeScript +for await (const item of client.simulation.tests.list()) { + console.log(item); +} +``` + + + + + +```python Python +client.simulation.tests.list( + *, + search: str | None | NotGiven = NOT_GIVEN, + simulation_type: Literal['agent_definition', 'prompt'] | None | NotGiven = NOT_GIVEN, + prompt_template_id: str | None | NotGiven = NOT_GIVEN, + limit: int | None | NotGiven = NOT_GIVEN, + summary: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> SyncPager[models.RunTestResponse] +``` + +```typescript TypeScript +client.simulation.tests.list(params: SimulationTestsListParams = {}, options?: RequestOptions): Pager + +export interface SimulationTestsListParams { + search?: string | null; + simulation_type?: "agent_definition" | "prompt" | null; + prompt_template_id?: string | null; + limit?: number | null; + /** Return the bounded list-card representation instead of the full nested run-test detail payload. */ + summary?: boolean | null; +} +``` + + + +#### Parameters + + + + + + + Return the bounded list-card representation instead of the full nested run-test detail payload. + + +The pager sends `page` itself; pass `limit` to change the page size. + +#### Returns + +A pager of [`RunTestResponse`](/docs/sdk/reference/simulation-models#runtestresponse) items: iterate it, or call `to_list()` (Python) / `toArray()` (TypeScript). + +### simulation.tests.run + +Start a saved simulation test asynchronously. Omit scenario_ids to run all configured scenarios. Uses existing provider/worker infrastructure and can incur usage charges. Poll get_test_execution with the returned execution_id, then read get_test_execution_analytics. + + + +**MCP tool**: `run_simulation` + + + +```python Python +result = client.simulation.tests.run("your-run-test-id") +``` + +```typescript TypeScript +const result = await client.simulation.tests.run("your-run-test-id"); +``` + + + + + +```python Python +client.simulation.tests.run( + run_test_id: str, + *, + scenario_ids: list[str] | None | NotGiven = NOT_GIVEN, + simulator_id: str | None | NotGiven = NOT_GIVEN, + select_all: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + extra_body: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.RunTestExecutionResponse +``` + +```typescript TypeScript +client.simulation.tests.run(runTestId: string, params: SimulationTestsRunParams = {}, options?: RequestOptions): Promise + +export interface SimulationTestsRunParams { + scenario_ids?: Array | null; + simulator_id?: string | null; + select_all?: boolean | null; +} +``` + + + +#### Parameters + + + Positional argument `run_test_id`. + + + + + +#### Returns + +[`RunTestExecutionResponse`](/docs/sdk/reference/simulation-models#runtestexecutionresponse). diff --git a/src/pages/docs/sdk/reference/spans.mdx b/src/pages/docs/sdk/reference/spans.mdx new file mode 100644 index 000000000..ebf86ab86 --- /dev/null +++ b/src/pages/docs/sdk/reference/spans.mdx @@ -0,0 +1,177 @@ +--- +title: "Spans" +description: "Reference for client.spans in the Future AGI Python and TypeScript SDKs: spans.get, spans.list." +--- + +`client.spans` on `fi.Client` (Python) and `client.spans` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Observability response models](/docs/sdk/reference/observability-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`spans.get`](#spansget) | Return an observation span by its identifier. | +| [`spans.list`](#spanslist) | List observation spans using the supplied filters. | + +## client.spans + +### spans.get + +Return an observation span by its identifier. + + + +**MCP tool**: `get_span` + + + +```python Python +result = client.spans.get("your-id") +``` + +```typescript TypeScript +const result = await client.spans.get("your-id"); +``` + + + + + +```python Python +client.spans.get( + id: str, + *, + test_execution_id: str | None | NotGiven = NOT_GIVEN, + call_execution_id: str | None | NotGiven = NOT_GIVEN, + project_id: str | None | NotGiven = NOT_GIVEN, + trace_id: str | None | NotGiven = NOT_GIVEN, + start_hour: str | None | NotGiven = NOT_GIVEN, + observation_type: str | None | NotGiven = NOT_GIVEN, + service_name: str | None | NotGiven = NOT_GIVEN, + expected_start_time: str | None | NotGiven = NOT_GIVEN, + expected_version: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.ObservationSpanDetailResult +``` + +```typescript TypeScript +client.spans.get(id: string, params: SpansGetParams = {}, options?: RequestOptions): Promise + +export interface SpansGetParams { + /** A run the caller can read; opens the hidden simulation project of that run's agent. */ + test_execution_id?: string | null; + /** A run the caller can read; opens the hidden simulation project of that run's agent. */ + call_execution_id?: string | null; + project_id?: string | null; + trace_id?: string | null; + start_hour?: string | null; + observation_type?: string | null; + service_name?: string | null; + expected_start_time?: string | null; + expected_version?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `id`. + + + A run the caller can read; opens the hidden simulation project of that run's agent. + + + A run the caller can read; opens the hidden simulation project of that run's agent. + + + + + + + + + +#### Returns + +[`ObservationSpanDetailResult`](/docs/sdk/reference/observability-models#observationspandetailresult). + +### spans.list + +List observation spans using the supplied filters. + + + +**MCP tool**: `list_spans` + + + +```python Python +result = client.spans.list() +``` + +```typescript TypeScript +const result = await client.spans.list(); +``` + + + + + +```python Python +client.spans.list( + *, + project_id: str | None | NotGiven = NOT_GIVEN, + user_id: str | None | NotGiven = NOT_GIVEN, + filters: str | None | NotGiven = NOT_GIVEN, + page_number: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + cursor: str | None | NotGiven = NOT_GIVEN, + cursor_mode: bool | None | NotGiven = NOT_GIVEN, + allow_sampled: bool | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.SpanObserveListResult +``` + +```typescript TypeScript +client.spans.list(params: SpansListParams = {}, options?: RequestOptions): Promise + +export interface SpansListParams { + project_id?: string | null; + user_id?: string | null; + filters?: string | null; + /** Zero-based numbered page. Pages whose required ordered work exceeds the finite read contract return HTTP 422 with code page_depth_exceeded; request an earlier page or narrow the time range. */ + page_number?: number | null; + page_size?: number | null; + /** Opaque continuation token returned by the previous page. When supplied, do not also send the numbered-page parameter. */ + cursor?: string | null; + cursor_mode?: boolean | null; + /** Omit for backward-compatible complete bounded pages, which may label total_rows as a lower bound. Send false to require an exact total, or true to opt in explicitly to lower-bound totals. */ + allow_sampled?: boolean | null; +} +``` + + + +#### Parameters + + + + + + Zero-based numbered page. Pages whose required ordered work exceeds the finite read contract return HTTP 422 with code page_depth_exceeded; request an earlier page or narrow the time range. + + + + Opaque continuation token returned by the previous page. When supplied, do not also send the numbered-page parameter. + + + + Omit for backward-compatible complete bounded pages, which may label total_rows as a lower bound. Send false to require an exact total, or true to opt in explicitly to lower-bound totals. + + +#### Returns + +[`SpanObserveListResult`](/docs/sdk/reference/observability-models#spanobservelistresult). diff --git a/src/pages/docs/sdk/reference/traces.mdx b/src/pages/docs/sdk/reference/traces.mdx new file mode 100644 index 000000000..0c9d29581 --- /dev/null +++ b/src/pages/docs/sdk/reference/traces.mdx @@ -0,0 +1,312 @@ +--- +title: "Traces" +description: "Reference for client.traces in the Future AGI Python and TypeScript SDKs: traces.error_analysis, traces.get, traces.list, traces.properties.list." +--- + +`client.traces` on `fi.Client` (Python) and `client.traces` on `Client` from `@future-agi/sdk` (TypeScript), with the nested resources `client.traces.properties`. The models these methods return are on [Observability response models](/docs/sdk/reference/observability-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`traces.error_analysis`](#traceserror_analysis) | Return the recorded error analysis for a trace. | +| [`traces.get`](#tracesget) | Return a trace by its identifier. | +| [`traces.list`](#traceslist) | Search traces using project, time range, status, and attribute filters. | +| [`traces.properties.list`](#tracespropertieslist) | Discover filter properties from the shared metrics catalog. | + +## client.traces + +### traces.error_analysis + +Return the recorded error analysis for a trace. + + + +**MCP tool**: `get_trace_error_analysis` + + + +```python Python +result = client.traces.error_analysis("your-trace-id") +``` + +```typescript TypeScript +const result = await client.traces.errorAnalysis("your-trace-id"); +``` + + + + + +```python Python +client.traces.error_analysis( + trace_id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.TraceErrorAnalysisResult +``` + +```typescript TypeScript +client.traces.errorAnalysis(traceId: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `trace_id`. + + +#### Returns + +[`TraceErrorAnalysisResult`](/docs/sdk/reference/observability-models#traceerroranalysisresult). + +### traces.get + +Return a trace by its identifier. + + + +**MCP tool**: `get_trace` + + + +```python Python +result = client.traces.get("your-id") +``` + +```typescript TypeScript +const result = await client.traces.get("your-id"); +``` + + + + + +```python Python +client.traces.get( + id: str, + *, + test_execution_id: str | None | NotGiven = NOT_GIVEN, + call_execution_id: str | None | NotGiven = NOT_GIVEN, + project_id: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.TraceDetailResult +``` + +```typescript TypeScript +client.traces.get(id: string, params: TracesGetParams = {}, options?: RequestOptions): Promise + +export interface TracesGetParams { + /** A run the caller can read; opens the hidden simulation project of that run's agent. */ + test_execution_id?: string | null; + /** A run the caller can read; opens the hidden simulation project of that run's agent. */ + call_execution_id?: string | null; + /** Project the detail was opened from. The same id can exist in several projects; when supplied, only that project's copy is read. */ + project_id?: string | null; +} +``` + + + +#### Parameters + + + Positional argument `id`. + + + A run the caller can read; opens the hidden simulation project of that run's agent. + + + A run the caller can read; opens the hidden simulation project of that run's agent. + + + Project the detail was opened from. The same id can exist in several projects; when supplied, only that project's copy is read. + + +#### Returns + +[`TraceDetailResult`](/docs/sdk/reference/observability-models#tracedetailresult). + +### traces.list + +Search traces using project, time range, status, and attribute filters. + + + +**MCP tool**: `search_traces` + + + +```python Python +result = client.traces.list() +``` + +```typescript TypeScript +const result = await client.traces.list(); +``` + + + + + +```python Python +client.traces.list( + *, + project_id: str | None | NotGiven = NOT_GIVEN, + project_version_id: str | None | NotGiven = NOT_GIVEN, + session_id: str | None | NotGiven = NOT_GIVEN, + filters: str | None | NotGiven = NOT_GIVEN, + page_number: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + cursor: str | None | NotGiven = NOT_GIVEN, + cursor_mode: bool | None | NotGiven = NOT_GIVEN, + attribute_keys: str | None | NotGiven = NOT_GIVEN, + allow_sampled: bool | None | NotGiven = NOT_GIVEN, + interval: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.TraceObserveListResult +``` + +```typescript TypeScript +client.traces.list(params: TracesListParams = {}, options?: RequestOptions): Promise + +export interface TracesListParams { + project_id?: string | null; + project_version_id?: string | null; + session_id?: string | null; + filters?: string | null; + /** Zero-based numbered page. Pages whose required ordered work exceeds the finite read contract return HTTP 422 with code page_depth_exceeded; request an earlier page or narrow the time range. */ + page_number?: number | null; + page_size?: number | null; + /** Opaque continuation token returned by the previous page. When supplied, do not also send the numbered-page parameter. */ + cursor?: string | null; + cursor_mode?: boolean | null; + /** JSON-encoded list of custom attribute keys to hydrate; only requested keys are returned. Each key resolves to its latest live span value by (start_time, span_id). Comma-separated simple keys remain supported. */ + attribute_keys?: string | null; + /** Omit for backward-compatible complete bounded pages, which may label total_rows as a lower bound. Send false to require an exact total. Send true to opt in explicitly to lower-bound totals and, on the first page, a clearly labelled bounded partial result when the full ordered prefix cannot be proven inside the read budget. */ + allow_sampled?: boolean | null; + interval?: string | null; +} +``` + + + +#### Parameters + + + + + + + Zero-based numbered page. Pages whose required ordered work exceeds the finite read contract return HTTP 422 with code page_depth_exceeded; request an earlier page or narrow the time range. + + + + Opaque continuation token returned by the previous page. When supplied, do not also send the numbered-page parameter. + + + + JSON-encoded list of custom attribute keys to hydrate; only requested keys are returned. Each key resolves to its latest live span value by (start_time, span_id). Comma-separated simple keys remain supported. + + + Omit for backward-compatible complete bounded pages, which may label total_rows as a lower bound. Send false to require an exact total. Send true to opt in explicitly to lower-bound totals and, on the first page, a clearly labelled bounded partial result when the full ordered prefix cannot be proven inside the read budget. + + + +#### Returns + +[`TraceObserveListResult`](/docs/sdk/reference/observability-models#traceobservelistresult). + +## client.traces.properties + +TypeScript: `client.traces.properties`. + +### traces.properties.list + +Discover filter properties from the shared metrics catalog. Pass cursor_mode=true, page_size (at most 50), source=traces (search_traces) or source=spans (list_spans), per_eval_config=true and project_ids when known. Use role=dimension to narrow to dimensions. Use name as column_id; set filter_config.col_type by mapping category system_metric to SYSTEM_METRIC, custom_attribute to SPAN_ATTRIBUTE, eval_metric to EVAL_METRIC, and annotation_metric to ANNOTATION. Preserve property_id and source for typed attribute bindings. Follow has_more/next_cursor by passing cursor; omit page and exclude_custom_attributes in cursor mode. + + + +**MCP tool**: `list_trace_properties` + + + +```python Python +result = client.traces.properties.list() +``` + +```typescript TypeScript +const result = await client.traces.properties.list(); +``` + + + + + +```python Python +client.traces.properties.list( + *, + workflow: Literal['observability', 'dataset', 'simulation'] | None | NotGiven = NOT_GIVEN, + project_ids: str | None | NotGiven = NOT_GIVEN, + agent_definition_id: str | None | NotGiven = NOT_GIVEN, + per_eval_config: bool | None | NotGiven = NOT_GIVEN, + exclude_custom_attributes: bool | None | NotGiven = NOT_GIVEN, + search: str | None | NotGiven = NOT_GIVEN, + category: Literal['system_metric', 'eval_metric', 'annotation_metric', 'custom_attribute', 'custom_column'] | None | NotGiven = NOT_GIVEN, + role: Literal['metric', 'dimension'] | None | NotGiven = NOT_GIVEN, + source: Literal['traces', 'spans', 'sessions', 'users', 'voice_calls', 'prompts', 'datasets', 'simulation', 'both', 'all'] | None | NotGiven = NOT_GIVEN, + page: int | None | NotGiven = NOT_GIVEN, + page_size: int | None | NotGiven = NOT_GIVEN, + cursor_mode: bool | None | NotGiven = NOT_GIVEN, + cursor: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.DashboardMetricsCatalogResult +``` + +```typescript TypeScript +client.traces.properties.list(params: TracesPropertiesListParams = {}, options?: RequestOptions): Promise + +export interface TracesPropertiesListParams { + workflow?: "observability" | "dataset" | "simulation" | null; + project_ids?: string | null; + agent_definition_id?: string | null; + per_eval_config?: boolean | null; + exclude_custom_attributes?: boolean | null; + search?: string | null; + category?: "system_metric" | "eval_metric" | "annotation_metric" | "custom_attribute" | "custom_column" | null; + role?: "metric" | "dimension" | null; + source?: "traces" | "spans" | "sessions" | "users" | "voice_calls" | "prompts" | "datasets" | "simulation" | "both" | "all" | null; + page?: number | null; + page_size?: number | null; + cursor_mode?: boolean | null; + cursor?: string | null; +} +``` + + + +#### Parameters + + + + + + + + + + + + + + + +#### Returns + +[`DashboardMetricsCatalogResult`](/docs/sdk/reference/observability-models#dashboardmetricscatalogresult). diff --git a/src/pages/docs/sdk/reference/usage.mdx b/src/pages/docs/sdk/reference/usage.mdx new file mode 100644 index 000000000..6edd61d83 --- /dev/null +++ b/src/pages/docs/sdk/reference/usage.mdx @@ -0,0 +1,69 @@ +--- +title: "Usage" +description: "Reference for client.usage in the Future AGI Python and TypeScript SDKs: usage.overview." +--- + +`client.usage` on `fi.Client` (Python) and `client.usage` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Account response models](/docs/sdk/reference/account-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`usage.overview`](#usageoverview) | Return the current organization's usage and cost overview. | + +## client.usage + +### usage.overview + +Return the current organization's usage and cost overview. + + + +**MCP tool**: `get_usage_overview` + + + +```python Python +result = client.usage.overview() +``` + +```typescript TypeScript +const result = await client.usage.overview(); +``` + + + + + +```python Python +client.usage.overview( + *, + period: str | None | NotGiven = NOT_GIVEN, + period_end: str | None | NotGiven = NOT_GIVEN, + workspace_id: str | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.UsageOverviewResult +``` + +```typescript TypeScript +client.usage.overview(params: UsageOverviewParams = {}, options?: RequestOptions): Promise + +export interface UsageOverviewParams { + period?: string | null; + period_end?: string | null; + workspace_id?: string | null; +} +``` + + + +#### Parameters + + + + + +#### Returns + +[`UsageOverviewResult`](/docs/sdk/reference/account-models#usageoverviewresult). diff --git a/src/pages/docs/sdk/reference/workspaces.mdx b/src/pages/docs/sdk/reference/workspaces.mdx new file mode 100644 index 000000000..462c427e8 --- /dev/null +++ b/src/pages/docs/sdk/reference/workspaces.mdx @@ -0,0 +1,106 @@ +--- +title: "Workspaces" +description: "Reference for client.workspaces in the Future AGI Python and TypeScript SDKs: workspaces.get, workspaces.list." +--- + +`client.workspaces` on `fi.Client` (Python) and `client.workspaces` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Account response models](/docs/sdk/reference/account-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). + +## Methods + +| Method | Description | +|---|---| +| [`workspaces.get`](#workspacesget) | Return a workspace by its identifier. | +| [`workspaces.list`](#workspaceslist) | List workspaces available to the authenticated user. | + +## client.workspaces + +### workspaces.get + +Return a workspace by its identifier. + + + +**MCP tool**: `get_workspace` + + + +```python Python +result = client.workspaces.get("your-workspace-id") +``` + +```typescript TypeScript +const result = await client.workspaces.get("your-workspace-id"); +``` + + + + + +```python Python +client.workspaces.get( + workspace_id: str, + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.WorkspaceManagementListResult +``` + +```typescript TypeScript +client.workspaces.get(workspaceId: string, options?: RequestOptions): Promise +``` + + + +#### Parameters + + + Positional argument `workspace_id`. + + +#### Returns + +[`WorkspaceManagementListResult`](/docs/sdk/reference/account-models#workspacemanagementlistresult). + +### workspaces.list + +List workspaces available to the authenticated user. + + + +**MCP tool**: `list_workspaces` + + + +```python Python +result = client.workspaces.list() +``` + +```typescript TypeScript +const result = await client.workspaces.list(); +``` + + + + + +```python Python +client.workspaces.list( + *, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.WorkspaceManagementListResult +``` + +```typescript TypeScript +client.workspaces.list(options?: RequestOptions): Promise +``` + + + +#### Parameters + +This method takes no parameters beyond the per-call `options`. + +#### Returns + +[`WorkspaceManagementListResult`](/docs/sdk/reference/account-models#workspacemanagementlistresult). diff --git a/src/styles/fapi-param.css b/src/styles/fapi-param.css new file mode 100644 index 000000000..6a1c91e0e --- /dev/null +++ b/src/styles/fapi-param.css @@ -0,0 +1,94 @@ +/* Shared field styles for ParamField and ResponseField (both import this file). */ +.fapi-param { + padding: 16px 0; + border-bottom: 1px solid var(--color-border-subtle); +} +.fapi-param:last-child { border-bottom: none; } + +.fapi-param-header { + display: inline-flex; + align-items: center; + gap: 8px; + flex-wrap: wrap; + max-width: 100%; + min-width: 0; +} +.fapi-param-name { + font-size: 13px; + font-weight: 600; + font-family: var(--font-mono); + color: var(--color-text-primary); +} +.fapi-param-meta { + display: inline-flex; + align-items: center; + gap: 6px; + flex-wrap: wrap; +} +.fapi-param-type { + font-size: 12px; + font-family: var(--font-mono); + color: #71717a; +} +.fapi-param-optional { + font-size: 12px; + color: #71717a; +} +.fapi-param-required { + font-size: 11px; + font-weight: 600; + color: #f87171; + text-transform: uppercase; + letter-spacing: 0.3px; +} +.fapi-param-constraint { + font-size: 11px; + font-family: var(--font-mono); + color: #71717a; + padding: 1px 6px; + background: rgba(255,255,255,0.04); + border: 1px solid rgba(255,255,255,0.08); + border-radius: 4px; +} +.fapi-param-default { + font-size: 12px; + color: #71717a; +} +.fapi-param-default code { + font-size: 11px; + padding: 1px 4px; + background: rgba(255,255,255,0.04); + border-radius: 3px; +} +.fapi-param-desc { + font-size: 13px; + color: #a1a1aa; + line-height: 1.6; + margin-top: 4px; +} +.fapi-param-desc p { margin: 0; } + +/* Enum values */ +.fapi-param-enum { + margin-top: 8px; +} +.fapi-param-enum-label { + font-size: 12px; + color: #71717a; + margin-bottom: 4px; + display: block; +} +.fapi-param-enum-values { + display: flex; + flex-wrap: wrap; + gap: 4px; +} +.fapi-param-enum-val { + font-size: 11px; + font-family: var(--font-mono); + padding: 2px 8px; + background: rgba(255,255,255,0.04); + border: 1px solid rgba(255,255,255,0.08); + border-radius: 4px; + color: #a1a1aa; +} From 30cd2ebe137c26acb5f92d22fe43204a5148990a Mon Sep 17 00:00:00 2001 From: tanmaycode1 Date: Wed, 4 Nov 2026 14:38:30 +0530 Subject: [PATCH 2/7] docs(sdk): one reference PR per SDK release, ready only once both packages are installable Close the chain backend contract -> SDK -> docs on the receiving side. The sync workflow now takes `sdk-release` dispatches from the SDK's release-please (stage: candidate, the version PR's head) and publish (stage: released, the published commit) workflows, a weekly schedule that syncs the newest published release, and a manual run for any ref as a labelled preview draft. scripts/sdk-reference-release.mjs decides the branch and the publish state: one branch per Python/TypeScript version pair, so a retry or the candidate->released transition rewrites the same PR instead of failing on an existing branch; a no-op diff opens nothing and closes a PR main already carries. A released claim is downgraded to a draft unless futureagi==X is on PyPI and @future-agi/sdk@Y is on npm, checked here, so the docs never describe an SDK users cannot install. The default is the newest published release, not the SDK's dev branch. node --test covers the decision; actionlint passes on the workflow. --- .github/workflows/sdk-reference-sync.yml | 133 +++++++++++++++----- package.json | 2 +- scripts/sdk-reference-release.mjs | 152 +++++++++++++++++++++++ scripts/sdk-reference-release.test.mjs | 76 ++++++++++++ scripts/sync-sdk-reference.mjs | 3 +- 5 files changed, 332 insertions(+), 34 deletions(-) create mode 100644 scripts/sdk-reference-release.mjs create mode 100644 scripts/sdk-reference-release.test.mjs diff --git a/.github/workflows/sdk-reference-sync.yml b/.github/workflows/sdk-reference-sync.yml index 5d549d9d0..30de07a7d 100644 --- a/.github/workflows/sdk-reference-sync.yml +++ b/.github/workflows/sdk-reference-sync.yml @@ -1,27 +1,45 @@ -# Refreshes the platform SDK reference (src/pages/docs/sdk/reference) from the SDK -# repository's generated pages and opens a PR against main. Run it by hand for a given SDK -# ref, let the SDK repository dispatch it on a release, or rely on the weekly run. +# The last link of the chain backend contract → futureagi-sdk → docs: syncs the +# platform SDK reference (src/pages/docs/sdk/reference) from the generated pages +# in a futureagi-sdk commit and opens or updates ONE pull request per SDK release. +# +# futureagi-sdk publish.yml → sdk-release {ref, stage: released} after PyPI and npm +# futureagi-sdk release-please → sdk-release {ref, stage: candidate} when a version PR is prepared +# schedule → newest published release (catches a missed dispatch) +# workflow_dispatch → any ref; a preview draft unless `stage` says otherwise +# +# scripts/sdk-reference-release.mjs decides the branch (one per Python/TypeScript +# version pair, so retries update the same PR) and whether the PR may be marked +# ready: only when BOTH packages at those versions are installable from PyPI and +# npm. Everything else is a draft. The docs site never documents an SDK that +# users cannot install. Pages are never edited here; fix the generator in the SDK. name: sdk-reference-sync on: + repository_dispatch: + types: [sdk-release] # client_payload: ref (full commit SHA), stage (released|candidate), source (URL) workflow_dispatch: inputs: sdk_ref: - description: futureagi-sdk ref to sync from (branch, tag or SHA) - default: dev - repository_dispatch: - types: [sdk-release] # client_payload.ref: the SDK ref to sync from + description: futureagi-sdk commit, tag or branch (empty = newest published release) + default: '' + stage: + description: 'released, candidate or preview (empty = preview for a ref, released otherwise)' + default: '' schedule: - - cron: '0 6 * * 1' # Mondays 06:00 UTC, from the SDK's dev branch + - cron: '0 6 * * 1' # Mondays 06:00 UTC permissions: contents: write pull-requests: write +concurrency: + group: sdk-reference-sync + cancel-in-progress: false + jobs: sync: runs-on: ubuntu-latest - timeout-minutes: 10 + timeout-minutes: 15 steps: # App token (not GITHUB_TOKEN): the org forbids Actions from creating PRs # with GITHUB_TOKEN, and App-minted tokens are exempt. Scoped to this repo. @@ -34,44 +52,95 @@ jobs: with: ref: main token: ${{ steps.app-token.outputs.token }} - - name: Resolve the SDK ref - id: ref + - uses: actions/setup-node@v4 + with: + node-version: 20 + - name: Resolve the SDK release + id: release env: - INPUT_REF: ${{ inputs.sdk_ref }} - DISPATCH_REF: ${{ github.event.client_payload.ref }} - run: echo "ref=${INPUT_REF:-${DISPATCH_REF:-dev}}" >> "$GITHUB_OUTPUT" - - name: Check out the generated reference from the SDK repository + GH_TOKEN: ${{ github.token }} + REF: ${{ inputs.sdk_ref || github.event.client_payload.ref }} + STAGE: ${{ inputs.stage || github.event.client_payload.stage }} + run: | + set -eu + if [ "$GITHUB_EVENT_NAME" = repository_dispatch ]; then + # A sender names the exact commit it published; a branch name could move under us. + [[ "$REF" =~ ^[0-9a-f]{40}$ ]] || { echo "::error::sdk-release needs client_payload.ref as a full commit SHA, got '$REF'"; exit 1; } + fi + args=() + [ -n "$REF" ] && args+=(--ref "$REF") + [ -n "$STAGE" ] && args+=(--stage "$STAGE") + node scripts/sdk-reference-release.mjs "${args[@]}" | tee -a "$GITHUB_OUTPUT" + - name: Check out the generated reference from that SDK commit uses: actions/checkout@v4 with: repository: future-agi/futureagi-sdk - ref: ${{ steps.ref.outputs.ref }} + ref: ${{ steps.release.outputs.sha }} path: .sdk sparse-checkout: docs/sdk-reference persist-credentials: false - - uses: actions/setup-node@v4 - with: - node-version: 20 - name: Sync the pages and the sidebar group run: node scripts/sync-sdk-reference.mjs --from .sdk - name: Check nav and content links run: node scripts/audit-links.mjs - - name: Open PR + - name: Open, update or finish the pull request env: GH_TOKEN: ${{ steps.app-token.outputs.token }} - SDK_REF: ${{ steps.ref.outputs.ref }} + SHA: ${{ steps.release.outputs.sha }} + REF: ${{ steps.release.outputs.ref }} + PY: ${{ steps.release.outputs.python }} + TS: ${{ steps.release.outputs.typescript }} + BACKEND: ${{ steps.release.outputs.backend }} + BRANCH: ${{ steps.release.outputs.branch }} + STAGE: ${{ steps.release.outputs.stage }} + PUBLISH: ${{ steps.release.outputs.publish }} + SOURCE: ${{ github.event.client_payload.source || format('{0}/{1}/actions/runs/{2}', github.server_url, github.repository, github.run_id) }} run: | set -eu + short=${SHA:0:12} + sdk="https://github.com/future-agi/futureagi-sdk" + number=$(gh pr list --head "$BRANCH" --base main --state open --json number --jq '.[0].number // empty') if git diff --quiet -- src/pages/docs/sdk/reference src/lib/sdk-reference.mjs; then - echo "reference already current"; exit 0 + if [ -z "$number" ]; then + echo "main already carries the reference of futureagi-sdk@$short; nothing to open" + exit 0 + fi + gh pr close "$number" --comment "main already carries the reference generated by futureagi-sdk@$short; nothing left to merge." \ + --delete-branch + exit 0 fi - sha=$(git -C .sdk rev-parse --short HEAD) - branch="chore/sdk-reference-${sha}" - git config user.name "futureagi-release-bot" - git config user.email "release-bot@futureagi.com" - git switch -c "$branch" + git config user.name "futureagi-release-bot[bot]" + git config user.email "futureagi-release-bot[bot]@users.noreply.github.com" + git switch -c "$BRANCH" git add src/pages/docs/sdk/reference src/lib/sdk-reference.mjs - git commit -m "docs(sdk): sync the platform SDK reference from futureagi-sdk@${sha}" - git push origin "$branch" - gh pr create --base main --head "$branch" \ - --title "docs(sdk): platform SDK reference from futureagi-sdk@${sha}" \ - --body "Generated pages from [future-agi/futureagi-sdk@${sha}](https://github.com/future-agi/futureagi-sdk/tree/${sha}/docs/sdk-reference) (ref \`${SDK_REF}\`), copied by \`scripts/sync-sdk-reference.mjs\`. Do not edit the pages here: fix the generator in the SDK repository and re-run the sync." + git commit -q -m "docs(sdk): sync the platform SDK reference from futureagi-sdk@$short" \ + -m "Python $PY, TypeScript $TS, backend contract $BACKEND ($STAGE)." + # One branch per release: a retry or the candidate→released transition rewrites it. + git push --force origin "$BRANCH" + case "$STAGE" in + released) title="docs(sdk): platform SDK reference for python-v$PY / typescript-v$TS" + stage_note="**Released.** \`futureagi==$PY\` is on [PyPI](https://pypi.org/project/futureagi/$PY/) and \`@future-agi/sdk@$TS\` on [npm](https://www.npmjs.com/package/@future-agi/sdk/v/$TS); this PR is ready for review." ;; + candidate) title="docs(sdk): platform SDK reference for python-v$PY / typescript-v$TS (candidate)" + stage_note="**Candidate (draft).** The SDK release is prepared but \`futureagi==$PY\` and \`@future-agi/sdk@$TS\` are not both installable yet. The publish workflow re-dispatches once they are, and this PR is marked ready then. Do not merge before." ;; + *) title="docs(sdk): platform SDK reference preview of futureagi-sdk@$short" + stage_note="**Preview (draft).** Generated from \`$REF\`, which is not a published release. For looking only; the released PR for these versions is opened by the SDK publish workflow." ;; + esac + cat > "$RUNNER_TEMP/body.md" </dev/null + fi + if [ "$PUBLISH" = ready ]; then + gh pr ready "$number" 2>/dev/null || true + fi + echo "future-agi/docs#$number ($STAGE, $PUBLISH)" diff --git a/package.json b/package.json index 273d686fd..2574aac50 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "astro": "astro", "new-doc": "node scripts/new-doc.mjs", "audit-links": "node scripts/audit-links.mjs", - "test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs", + "test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/sdk-reference-release.test.mjs", "test:integrations:browser": "node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs", "check:integrations": "tsc --allowJs --checkJs --noEmit --strict --types node --target ES2022 --module nodenext src/lib/integrations.mjs" }, diff --git a/scripts/sdk-reference-release.mjs b/scripts/sdk-reference-release.mjs new file mode 100644 index 000000000..4306a4a1c --- /dev/null +++ b/scripts/sdk-reference-release.mjs @@ -0,0 +1,152 @@ +// @ts-check +/** + * Decide which futureagi-sdk revision the reference should be synced from, and + * whether the resulting docs PR may be published as stable or must stay a draft. + * + * node scripts/sdk-reference-release.mjs [--ref ] [--stage released|candidate|preview] [--json] + * + * Without --ref it picks the newest published SDK release: the commit of the + * newest `python-v*` tag. The result (printed as `key=value` lines, or JSON with + * --json) carries the full commit SHA, the Python/TypeScript versions from the + * SDK's release manifest at that commit, the backend release the contract was + * synced from, and `branch`, the docs branch for this release: one branch (so one + * PR) per SDK version pair, however many times the sync runs. + * + * `stage` is what the caller claims; `publish` is what the registries confirm. + * A `released` claim is downgraded to `candidate` unless BOTH packages at those + * versions are installable from PyPI and npm, so a docs PR never leaves draft + * for an SDK users cannot install yet. `preview` (any ref, usually dev) is + * always a draft and gets its own branch keyed by commit. + * + * Reads only public endpoints (api.github.com, pypi.org, registry.npmjs.org); + * GH_TOKEN or GITHUB_TOKEN is used for GitHub when present to avoid rate limits. + * .github/workflows/sdk-reference-sync.yml runs it; `node --test scripts/` covers it. + */ +import process from 'node:process'; + +export const SDK_REPO = 'future-agi/futureagi-sdk'; +const STAGES = new Set(['released', 'candidate', 'preview']); + +/** @param {string} url @param {RequestInit} [init] */ +async function fetchJson(url, init) { + const response = await fetch(url, init); + if (!response.ok) throw new Error(`${url}: HTTP ${response.status}`); + return response.json(); +} + +/** @param {string} path */ +async function github(path) { + const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN; + /** @type {Record} */ + const headers = { accept: 'application/vnd.github+json', 'user-agent': 'future-agi-docs-sdk-reference' }; + if (token) headers.authorization = `Bearer ${token}`; + return fetchJson(`https://api.github.com/repos/${SDK_REPO}/${path}`, { headers }); +} + +/** The newest python-v* tag's name (by semantic version, not by push order). */ +export function newestPythonTag(/** @type {{ref: string}[]} */ refs) { + const versions = refs + .map((ref) => ref.ref.replace('refs/tags/', '')) + .map((tag) => ({ tag, match: /^python-v(\d+)\.(\d+)\.(\d+)$/.exec(tag) })) + .filter((entry) => entry.match) + .map((entry) => ({ tag: entry.tag, version: entry.match.slice(1, 4).map(Number) })) + .sort((a, b) => a.version[0] - b.version[0] || a.version[1] - b.version[1] || a.version[2] - b.version[2]); + if (!versions.length) throw new Error(`${SDK_REPO} has no python-v* release tag yet`); + return versions[versions.length - 1].tag; +} + +/** @param {string} ref a tag, branch or commit; returns the full commit SHA. */ +async function resolveSha(ref) { + const commit = await github(`commits/${encodeURIComponent(ref)}`); + if (!/^[0-9a-f]{40}$/.test(commit.sha)) throw new Error(`cannot resolve ${ref} to a commit`); + return commit.sha; +} + +/** @param {string} path @param {string} sha */ +async function fileAt(path, sha) { + const file = await github(`contents/${path}?ref=${sha}`); + return Buffer.from(file.content, 'base64').toString('utf-8'); +} + +/** @param {string} version */ +export async function onPyPI(version) { + const response = await fetch(`https://pypi.org/pypi/futureagi/${version}/json`); + return response.status === 200; +} + +/** @param {string} version */ +export async function onNpm(version) { + const response = await fetch(`https://registry.npmjs.org/@future-agi%2fsdk/${version}`); + return response.status === 200; +} + +/** + * Pure part: branch and publish decision from the facts. + * @param {{stage: string, sha: string, python: string, typescript: string, installable: boolean}} facts + */ +export function decide({ stage, sha, python, typescript, installable }) { + if (!STAGES.has(stage)) throw new Error(`stage must be one of ${[...STAGES].join(', ')}, not ${stage}`); + if (stage === 'preview') { + return { branch: `sdk-reference/preview-${sha.slice(0, 12)}`, publish: 'draft', stage }; + } + const branch = `sdk-reference/python-v${python}-typescript-v${typescript}`; + if (stage === 'released' && installable) return { branch, publish: 'ready', stage }; + return { branch, publish: 'draft', stage: 'candidate' }; +} + +/** + * @param {{ref?: string, stage?: string}} options + * @param {{resolveSha?: typeof resolveSha, fileAt?: typeof fileAt, tags?: () => Promise<{ref: string}[]>, onPyPI?: typeof onPyPI, onNpm?: typeof onNpm}} [io] + */ +export async function resolve(options, io = {}) { + const get = { + resolveSha: io.resolveSha ?? resolveSha, + fileAt: io.fileAt ?? fileAt, + tags: io.tags ?? (() => github('git/matching-refs/tags/python-v')), + onPyPI: io.onPyPI ?? onPyPI, + onNpm: io.onNpm ?? onNpm, + }; + let ref = options.ref?.trim() || ''; + let stage = options.stage?.trim() || (ref ? 'preview' : 'released'); + if (!ref) { + ref = newestPythonTag(await get.tags()); + stage = options.stage?.trim() || 'released'; + } + const sha = await get.resolveSha(ref); + const manifest = JSON.parse(await get.fileAt('.release-please-manifest.json', sha)); + const python = manifest['python']; + const typescript = manifest['typescript/futureagi']; + if (!python || !typescript) throw new Error(`release manifest at ${sha} lacks the python or typescript/futureagi version`); + const backend = (await get.fileAt('sdkgen/contracts/BACKEND_VERSION', sha)).trim(); + const installable = stage === 'released' ? (await get.onPyPI(python)) && (await get.onNpm(typescript)) : false; + const decision = decide({ stage, sha, python, typescript, installable }); + return { ref, sha, python, typescript, backend, installable, ...decision }; +} + +function parseArgs(argv) { + /** @type {{ref?: string, stage?: string, json?: boolean}} */ + const options = {}; + for (let i = 0; i < argv.length; i++) { + if (argv[i] === '--ref') options.ref = argv[++i]; + else if (argv[i] === '--stage') options.stage = argv[++i]; + else if (argv[i] === '--json') options.json = true; + else throw new Error(`unknown argument ${argv[i]}`); + } + return options; +} + +if (process.argv[1] && import.meta.url === new URL(process.argv[1], 'file://').href) { + const options = parseArgs(process.argv.slice(2)); + resolve(options) + .then((result) => { + if (options.json) { + console.log(JSON.stringify(result, null, 2)); + } else { + for (const [key, value] of Object.entries(result)) console.log(`${key}=${value}`); + } + }) + .catch((error) => { + console.error(error.message); + process.exit(1); + }); +} diff --git a/scripts/sdk-reference-release.test.mjs b/scripts/sdk-reference-release.test.mjs new file mode 100644 index 000000000..806774adb --- /dev/null +++ b/scripts/sdk-reference-release.test.mjs @@ -0,0 +1,76 @@ +// @ts-check +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { decide, newestPythonTag, resolve } from './sdk-reference-release.mjs'; + +const SHA = 'd4631b0b5208e11ef55706b531609be427888704'; +const files = { + '.release-please-manifest.json': JSON.stringify({ python: '0.7.0', 'typescript/futureagi': '0.2.0' }), + 'sdkgen/contracts/BACKEND_VERSION': 'v1.58.0\n', +}; + +/** @param {{pypi?: boolean, npm?: boolean, tags?: string[]}} world */ +function io(world = {}) { + return { + resolveSha: async (/** @type {string} */ ref) => (ref === 'missing' ? Promise.reject(new Error('404')) : SHA), + fileAt: async (/** @type {string} */ path) => files[path], + tags: async () => (world.tags ?? ['python-v0.6.9', 'python-v0.7.0', 'python-v0.6.14', 'typescript-v0.2.0']).map((t) => ({ ref: `refs/tags/${t}` })), + onPyPI: async () => world.pypi ?? false, + onNpm: async () => world.npm ?? false, + }; +} + +test('newest python tag is chosen by version, not by string order', () => { + const tags = ['python-v0.9.1', 'python-v0.10.0', 'python-v0.9.12'].map((t) => ({ ref: `refs/tags/${t}` })); + assert.equal(newestPythonTag(tags), 'python-v0.10.0'); + assert.throws(() => newestPythonTag([{ ref: 'refs/tags/typescript-v0.2.0' }]), /no python-v\* release tag/); +}); + +test('one branch per SDK version pair; preview branches are keyed by commit', () => { + const facts = { sha: SHA, python: '0.7.0', typescript: '0.2.0' }; + assert.deepEqual(decide({ ...facts, stage: 'released', installable: true }), { + branch: 'sdk-reference/python-v0.7.0-typescript-v0.2.0', publish: 'ready', stage: 'released', + }); + assert.deepEqual(decide({ ...facts, stage: 'candidate', installable: false }), { + branch: 'sdk-reference/python-v0.7.0-typescript-v0.2.0', publish: 'draft', stage: 'candidate', + }); + assert.deepEqual(decide({ ...facts, stage: 'preview', installable: false }), { + branch: 'sdk-reference/preview-d4631b0b5208', publish: 'draft', stage: 'preview', + }); + assert.throws(() => decide({ ...facts, stage: 'stable', installable: true }), /stage must be one of/); +}); + +test('a released claim stays a draft until both packages are installable', async () => { + const claim = { ref: SHA, stage: 'released' }; + assert.equal((await resolve(claim, io({ pypi: true, npm: true }))).publish, 'ready'); + const onlyPython = await resolve(claim, io({ pypi: true, npm: false })); + assert.equal(onlyPython.publish, 'draft'); + assert.equal(onlyPython.stage, 'candidate'); + assert.equal((await resolve(claim, io({ pypi: false, npm: true }))).publish, 'draft'); +}); + +test('no ref means the newest published release; a ref without a stage is a preview', async () => { + const release = await resolve({}, io({ pypi: true, npm: true })); + assert.equal(release.ref, 'python-v0.7.0'); + assert.equal(release.stage, 'released'); + assert.equal(release.publish, 'ready'); + assert.equal(release.backend, 'v1.58.0'); + const preview = await resolve({ ref: 'dev' }, io({ pypi: true, npm: true })); + assert.equal(preview.stage, 'preview'); + assert.equal(preview.publish, 'draft'); + assert.equal(preview.installable, false, 'registries are not consulted for a preview'); +}); + +test('candidate and released runs for the same versions share a branch', async () => { + const candidate = await resolve({ ref: SHA, stage: 'candidate' }, io()); + const released = await resolve({ ref: SHA, stage: 'released' }, io({ pypi: true, npm: true })); + assert.equal(candidate.branch, released.branch); + assert.equal(candidate.publish, 'draft'); + assert.equal(released.publish, 'ready'); +}); + +test('an unresolvable ref or a manifest without both versions fails', async () => { + await assert.rejects(resolve({ ref: 'missing' }, io()), /404/); + const broken = { ...io(), fileAt: async () => JSON.stringify({ python: '0.7.0' }) }; + await assert.rejects(resolve({ ref: SHA }, broken), /lacks the python or typescript/); +}); diff --git a/scripts/sync-sdk-reference.mjs b/scripts/sync-sdk-reference.mjs index ad7239407..0f9b757ae 100644 --- a/scripts/sync-sdk-reference.mjs +++ b/scripts/sync-sdk-reference.mjs @@ -9,7 +9,8 @@ * This script replaces `src/pages/docs/sdk/reference/` with those pages and rewrites * `src/lib/sdk-reference.mjs`, the sidebar group `navigation.ts` imports. Never edit the * copied pages by hand: fix the generator in the SDK repository and sync again. - * `.github/workflows/sdk-reference-sync.yml` runs this and opens a PR. + * `.github/workflows/sdk-reference-sync.yml` runs this for the SDK commit chosen by + * `scripts/sdk-reference-release.mjs` and opens or updates one PR per SDK release. */ import fs from 'node:fs'; import path from 'node:path'; From 5b6695816aa5b7d205096260a4af0c46f026cfd7 Mon Sep 17 00:00:00 2001 From: tanmaycode1 Date: Wed, 4 Nov 2026 16:00:02 +0530 Subject: [PATCH 3/7] docs(sdk): resync the corrected reference; contain its tables and endpoint paths at phone width Review findings on #1106 (nik13). The pages are resynced from futureagi-sdk 3269d58, where the generator was fixed: ref-aware example values (dashboards query shows an object for time_range), error imports from @future-agi/sdk/platform, no TypeScript strictResponses claim. Nothing was edited by hand here. Phone width: every generated table now sits in
, styled in global.css as a bounded horizontal scroller (max-width 100%, overflow-x auto), so a long identifier scrolls inside the table instead of widening the page; h3/h4 may break inside a single long identifier; and the ApiEndpoint badge lets a long path wrap (min-w-0, overflow-wrap: anywhere), which was the other source of document overflow. Nothing is clipped. scripts/sdk-reference-mobile.cjs (part of test:integrations:browser, so it runs in pr-checks after the preview starts) loads every page of the reference group at a 390 px viewport and fails if the document scrolls horizontally, if a table is outside .sdk-ref-table, or if any heading, cell or code block starts left of the viewport. Locally: 34 pages fit 390 px (annotation-queues was 536 px, prompts 402 px, prompt models 425 px before). --- package.json | 2 +- scripts/sdk-reference-mobile.cjs | 59 +++++++++ src/components/docs/ApiEndpoint.astro | 3 +- .../docs/sdk/reference/account-models.mdx | 8 +- src/pages/docs/sdk/reference/account.mdx | 4 + src/pages/docs/sdk/reference/agents.mdx | 4 + src/pages/docs/sdk/reference/alerts.mdx | 4 + .../docs/sdk/reference/annotation-models.mdx | 6 +- .../docs/sdk/reference/annotation-queues.mdx | 4 + src/pages/docs/sdk/reference/annotations.mdx | 4 + src/pages/docs/sdk/reference/dashboards.mdx | 8 +- .../sdk/reference/datasets-evals-models.mdx | 6 +- src/pages/docs/sdk/reference/datasets.mdx | 4 + .../docs/sdk/reference/error-clusters.mdx | 117 +++++++++++++++++- src/pages/docs/sdk/reference/evals.mdx | 4 + src/pages/docs/sdk/reference/experiments.mdx | 4 + .../sdk/reference/file-knowledge-bases.mdx | 4 + .../docs/sdk/reference/gateway-models.mdx | 6 +- src/pages/docs/sdk/reference/gateway.mdx | 4 + src/pages/docs/sdk/reference/index.mdx | 20 ++- .../sdk/reference/knowledge-bases-models.mdx | 6 +- .../docs/sdk/reference/knowledge-bases.mdx | 4 + src/pages/docs/sdk/reference/models.mdx | 4 + .../sdk/reference/observability-models.mdx | 21 +++- .../docs/sdk/reference/optimizations.mdx | 4 + src/pages/docs/sdk/reference/projects.mdx | 4 + .../docs/sdk/reference/prompts-models.mdx | 6 +- src/pages/docs/sdk/reference/prompts.mdx | 4 + .../docs/sdk/reference/provider-keys.mdx | 4 + src/pages/docs/sdk/reference/scores.mdx | 4 + src/pages/docs/sdk/reference/sessions.mdx | 4 + .../docs/sdk/reference/simulation-models.mdx | 6 +- src/pages/docs/sdk/reference/simulation.mdx | 4 + src/pages/docs/sdk/reference/spans.mdx | 4 + src/pages/docs/sdk/reference/traces.mdx | 7 ++ src/pages/docs/sdk/reference/usage.mdx | 4 + src/pages/docs/sdk/reference/workspaces.mdx | 4 + src/styles/global.css | 30 +++++ 38 files changed, 381 insertions(+), 18 deletions(-) create mode 100644 scripts/sdk-reference-mobile.cjs diff --git a/package.json b/package.json index 2574aac50..c371ff42b 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "new-doc": "node scripts/new-doc.mjs", "audit-links": "node scripts/audit-links.mjs", "test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/sdk-reference-release.test.mjs", - "test:integrations:browser": "node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs", + "test:integrations:browser": "node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs && node scripts/sdk-reference-mobile.cjs", "check:integrations": "tsc --allowJs --checkJs --noEmit --strict --types node --target ES2022 --module nodenext src/lib/integrations.mjs" }, "dependencies": { diff --git a/scripts/sdk-reference-mobile.cjs b/scripts/sdk-reference-mobile.cjs new file mode 100644 index 000000000..f63d6fead --- /dev/null +++ b/scripts/sdk-reference-mobile.cjs @@ -0,0 +1,59 @@ +// Phone-width regression for the generated platform SDK reference: every page in the +// sidebar group must fit a 390 px viewport with no horizontal page scroll, and every +// reference table must sit in a bounded scroller (.sdk-ref-table) so wide identifiers +// scroll inside the table instead of widening the document. Runs against the preview +// on 127.0.0.1:4321 (npm run build && npm run preview), like integrations.browser.cjs. +const { chromium } = require('playwright'); +const assert = require('node:assert/strict'); +const path = require('node:path'); + +const BASE = 'http://127.0.0.1:4321'; +const WIDTH = 390; + +async function routes() { + const { sdkReferenceNavigation } = await import(path.join(__dirname, '..', 'src', 'lib', 'sdk-reference.mjs')); + const out = []; + const walk = (items) => { + for (const item of items) { + if (item.href) out.push(item.href); + if (item.items) walk(item.items); + } + }; + walk(sdkReferenceNavigation.items); + return out; +} + +(async () => { + let ready = false; + for (let i = 0; i < 30 && !ready; i++) { + try { if ((await fetch(BASE + '/docs/sdk/reference')).ok) ready = true; else await new Promise((r) => setTimeout(r, 1000)); } catch { await new Promise((r) => setTimeout(r, 1000)); } + } + assert.ok(ready, 'Start the docs preview on 127.0.0.1:4321 before running browser checks'); + const hrefs = await routes(); + assert.ok(hrefs.length >= 30, `expected the full reference in the sidebar, found ${hrefs.length} routes`); + const browser = await chromium.launch({ headless: true }); + const ctx = await browser.newContext({ viewport: { width: WIDTH, height: 844 }, colorScheme: 'dark' }); + const page = await ctx.newPage(); + const failures = []; + for (const href of hrefs) { + await page.goto(BASE + href + '/', { waitUntil: 'networkidle' }); + const m = await page.evaluate(() => ({ + scrollWidth: document.documentElement.scrollWidth, + clientWidth: document.documentElement.clientWidth, + tables: document.querySelectorAll('.docs-content table').length, + unwrapped: [...document.querySelectorAll('.docs-content table')].filter((t) => !t.closest('.sdk-ref-table')).length, + offscreen: [...document.querySelectorAll('.docs-content h2, .docs-content h3, .docs-content td, .docs-content pre')] + .filter((el) => el.getBoundingClientRect().left < 0).length, + })); + if (m.scrollWidth > m.clientWidth) failures.push(`${href}: document scrolls to ${m.scrollWidth}px at a ${m.clientWidth}px viewport`); + if (m.unwrapped) failures.push(`${href}: ${m.unwrapped} table(s) not inside .sdk-ref-table`); + if (m.offscreen) failures.push(`${href}: ${m.offscreen} element(s) start left of the viewport (clipped content)`); + console.log(`${href}: ${m.scrollWidth}px wide, ${m.tables} table(s)`); + } + await browser.close(); + assert.deepEqual(failures, [], failures.join('\n')); + console.log(`sdk reference mobile: ${hrefs.length} pages fit ${WIDTH}px with bounded tables`); +})().catch((error) => { + console.error(error.message || error); + process.exit(1); +}); diff --git a/src/components/docs/ApiEndpoint.astro b/src/components/docs/ApiEndpoint.astro index 88f7e9ae8..5f4b5b0d4 100644 --- a/src/components/docs/ApiEndpoint.astro +++ b/src/components/docs/ApiEndpoint.astro @@ -27,5 +27,6 @@ const methodColors = { ]}> {method} - {path} + + {path}
diff --git a/src/pages/docs/sdk/reference/account-models.mdx b/src/pages/docs/sdk/reference/account-models.mdx index d1f7c0147..742b7ffc0 100644 --- a/src/pages/docs/sdk/reference/account-models.mdx +++ b/src/pages/docs/sdk/reference/account-models.mdx @@ -3,17 +3,21 @@ title: "Account response models" description: "The 8 response models returned by the account resources of the Future AGI Python and TypeScript SDKs, with every field and its type." --- -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)). +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. ## Models +
+ | Model | Fields | |---|---| | `UsageOverviewDimension` | `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` | | `UsageOverviewResult` | `plan: string`, `plan_display_name: string`, `platform_fee: number`, `period: string`, `billing_period_start: string`, `billing_period_end: string`, `total_estimated_cost: number`, `total_with_platform: number`, `dimensions:` [`UsageOverviewDimension`](#usageoverviewdimension)[], `pending_cancel: boolean`, `cancel_at: string` | | `UsageTierBreakdown` | `tier_start: number`, `tier_end: number`, `quantity: number`, `rate: number`, `cost: number` | | `UserInfoOrganization` | `id: string`, `name: string`, `display_name: string`, `ws_enabled: boolean` | -| `UserInfoResponse` | `id: string`, `email: string`, `name: string`, `organization_role: string`, `organization:` [`UserInfoOrganization`](#userinfoorganization), `created_at: string`, `status: string`, `role: string`, `goals: string[]`, `remember_me: boolean`, `get_started_completed: boolean`, `onboarding_completed: boolean`, `ws_enabled: boolean`, `requires_org_setup: boolean`, `default_workspace_id: string`, `default_workspace_name: string`, `default_workspace_display_name: string`, `default_workspace_role: string`, `org_level: integer`, `ws_level: integer`, `effective_level: integer`, `has_2fa_enabled: boolean`, `two_factor_methods:` [`UserInfoTwoFactorMethods`](#userinfotwofactormethods), `org_2fa_required: boolean`, `org_2fa_grace_ends_at: string` | +| `UserInfoResponse` | `id: string`, `email: string`, `name: string`, `organization_role: string`, `organization:` [`UserInfoOrganization`](#userinfoorganization), `created_at: string`, `status: string`, `role: string`, `goals: string[]`, `remember_me: boolean`, `get_started_completed: boolean`, `onboarding_completed: boolean`, `ws_enabled: boolean`, `requires_org_setup: boolean`, `default_workspace_id: string`, `default_workspace_name: string`, `default_workspace_display_name: string`, `default_workspace_role: string`, `org_level: integer`, `ws_level: integer`, `effective_level: integer`, `has_2fa_enabled: boolean`, `two_factor_methods:` [`UserInfoTwoFactorMethods`](#userinfotwofactormethods), `org_2fa_required: boolean`, `org_2fa_grace_ends_at: string`, `restrict_simulate_to_environments: boolean` | | `UserInfoTwoFactorMethods` | `totp: boolean`, `passkey: boolean` | | `WorkspaceManagementItem` | `id: string`, `name: string`, `display_name: string`, `description: string`, `is_default: boolean`, `member_count: integer`, `created_at: string`, `created_by: string` | | `WorkspaceManagementListResult` | `organization: string`, `workspaces:` [`WorkspaceManagementItem`](#workspacemanagementitem)[], `total: integer` | + +
diff --git a/src/pages/docs/sdk/reference/account.mdx b/src/pages/docs/sdk/reference/account.mdx index be4b0b198..e9a5a93b5 100644 --- a/src/pages/docs/sdk/reference/account.mdx +++ b/src/pages/docs/sdk/reference/account.mdx @@ -7,10 +7,14 @@ description: "Reference for client.account in the Future AGI Python and TypeScri ## Methods +
+ | Method | Description | |---|---| | [`account.whoami`](#accountwhoami) | Return the authenticated user, organization, and workspace context. | +
+ ## client.account ### account.whoami diff --git a/src/pages/docs/sdk/reference/agents.mdx b/src/pages/docs/sdk/reference/agents.mdx index caddaf5a2..bc129bdc6 100644 --- a/src/pages/docs/sdk/reference/agents.mdx +++ b/src/pages/docs/sdk/reference/agents.mdx @@ -7,6 +7,8 @@ description: "Reference for client.agents in the Future AGI Python and TypeScrip ## Methods +
+ | Method | Description | |---|---| | [`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 | [`agents.update`](#agentsupdate) | Edit an agent definition. | | [`agents.versions.create`](#agentsversionscreate) | Snapshot agent configuration into a new version and activate it. | +
+ ## client.agents ### agents.create diff --git a/src/pages/docs/sdk/reference/alerts.mdx b/src/pages/docs/sdk/reference/alerts.mdx index 173e4c8d8..bcf1cf5e3 100644 --- a/src/pages/docs/sdk/reference/alerts.mdx +++ b/src/pages/docs/sdk/reference/alerts.mdx @@ -7,11 +7,15 @@ description: "Reference for client.alerts in the Future AGI Python and TypeScrip ## Methods +
+ | Method | Description | |---|---| | [`alerts.logs.list`](#alertslogslist) | List alerts that have fired in numbered pages. | | [`alerts.rules.list`](#alertsruleslist) | List the configured alert monitors - what each one watches, its threshold and its project. | +
+ ## client.alerts ## client.alerts.logs diff --git a/src/pages/docs/sdk/reference/annotation-models.mdx b/src/pages/docs/sdk/reference/annotation-models.mdx index 01ef5094d..8a0f560de 100644 --- a/src/pages/docs/sdk/reference/annotation-models.mdx +++ b/src/pages/docs/sdk/reference/annotation-models.mdx @@ -3,10 +3,12 @@ title: "Annotation response models" description: "The 30 response models returned by the annotation resources of the Future AGI Python and TypeScript SDKs, with every field and its type." --- -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)). +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. ## Models +
+ | Model | Fields | |---|---| | `AnnotationQueue` | `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 | `QueueRemoveLabelResult` | `removed: boolean` | | `QueueSubmitAnnotationsResult` | `submitted: integer` | | `Score` | `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` | + +
diff --git a/src/pages/docs/sdk/reference/annotation-queues.mdx b/src/pages/docs/sdk/reference/annotation-queues.mdx index 671a47ddb..de13a491e 100644 --- a/src/pages/docs/sdk/reference/annotation-queues.mdx +++ b/src/pages/docs/sdk/reference/annotation-queues.mdx @@ -7,6 +7,8 @@ description: "Reference for client.annotation_queues in the Future AGI Python an ## Methods +
+ | Method | Description | |---|---| | [`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 | [`annotation_queues.items.skip`](#annotation_queuesitemsskip) | Skip a queue item and return the next one to work on. | | [`annotation_queues.items.submit`](#annotation_queuesitemssubmit) | Submit annotation values for an item in an annotation queue. | +
+ ## client.annotation_queues ### annotation_queues.add_label diff --git a/src/pages/docs/sdk/reference/annotations.mdx b/src/pages/docs/sdk/reference/annotations.mdx index d1b95cf8d..858b63c2d 100644 --- a/src/pages/docs/sdk/reference/annotations.mdx +++ b/src/pages/docs/sdk/reference/annotations.mdx @@ -7,6 +7,8 @@ description: "Reference for client.annotations in the Future AGI Python and Type ## Methods +
+ | Method | Description | |---|---| | [`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 | [`annotations.labels.get`](#annotationslabelsget) | Return an annotation label by id. | | [`annotations.labels.list`](#annotationslabelslist) | List annotation labels, optionally filtered by project, type or search text. | +
+ ## client.annotations ### annotations.bulk_create diff --git a/src/pages/docs/sdk/reference/dashboards.mdx b/src/pages/docs/sdk/reference/dashboards.mdx index fb780a88c..c6e7f1bd0 100644 --- a/src/pages/docs/sdk/reference/dashboards.mdx +++ b/src/pages/docs/sdk/reference/dashboards.mdx @@ -7,6 +7,8 @@ description: "Reference for client.dashboards in the Future AGI Python and TypeS ## Methods +
+ | Method | Description | |---|---| | [`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 | [`dashboards.widgets.query`](#dashboardswidgetsquery) | Execute a saved widget's query and return its chart data. | | [`dashboards.widgets.update`](#dashboardswidgetsupdate) | Update selected fields on a dashboard widget, such as its query_config, chart_config, or layout. | +
+ ## client.dashboards ### dashboards.create @@ -307,12 +311,12 @@ Run an ad-hoc dashboard query (time_range and metrics, with optional filters and ```python Python -result = client.dashboards.query(time_range="your-time-range", metrics=[]) +result = client.dashboards.query(time_range={"preset": "30m"}, metrics=[]) ``` ```typescript TypeScript const result = await client.dashboards.query({ - time_range: "your-time-range", + time_range: { preset: "30m" }, metrics: [], }); ``` diff --git a/src/pages/docs/sdk/reference/datasets-evals-models.mdx b/src/pages/docs/sdk/reference/datasets-evals-models.mdx index 2f3fce903..171a1aef6 100644 --- a/src/pages/docs/sdk/reference/datasets-evals-models.mdx +++ b/src/pages/docs/sdk/reference/datasets-evals-models.mdx @@ -3,10 +3,12 @@ title: "Datasets & evals response models" 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." --- -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)). +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. ## Models +
+ | Model | Fields | |---|---| | `Column` | `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`, | `OptimizationsCreateResult` | `id: string`, `name: string`, `optimizer_algorithm: string`, `optimizer_config: any`, `created_at: string` | | `_EvalTaskListResultResponse` | `metadata: any`, `table:` [`_EvalTaskListRowResponse`](#_evaltasklistrowresponse)[], `config: any[]` | | `_EvalTaskListRowResponse` | `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` | + +
diff --git a/src/pages/docs/sdk/reference/datasets.mdx b/src/pages/docs/sdk/reference/datasets.mdx index 981d201ed..24a93fbc5 100644 --- a/src/pages/docs/sdk/reference/datasets.mdx +++ b/src/pages/docs/sdk/reference/datasets.mdx @@ -7,6 +7,8 @@ description: "Reference for client.datasets in the Future AGI Python and TypeScr ## Methods +
+ | Method | Description | |---|---| | [`datasets.create`](#datasetscreate) | Create an empty dataset in the current workspace. | @@ -30,6 +32,8 @@ description: "Reference for client.datasets in the Future AGI Python and TypeScr | [`datasets.prompts.update`](#datasetspromptsupdate) | Update a dataset prompt column using dataset_id, column_id and config. | | [`datasets.rows.add`](#datasetsrowsadd) | Add rows to an existing dataset using cells with column_name and value. | +
+ ## client.datasets ### datasets.create diff --git a/src/pages/docs/sdk/reference/error-clusters.mdx b/src/pages/docs/sdk/reference/error-clusters.mdx index 61039f410..792eee5e3 100644 --- a/src/pages/docs/sdk/reference/error-clusters.mdx +++ b/src/pages/docs/sdk/reference/error-clusters.mdx @@ -1,16 +1,22 @@ --- title: "Error clusters" -description: "Reference for client.error_clusters in the Future AGI Python and TypeScript SDKs: error_clusters.get, error_clusters.list." +description: "Reference for client.error_clusters in the Future AGI Python and TypeScript SDKs: error_clusters.get, error_clusters.list, error_clusters.list_traces, error_clusters.overview." --- `client.error_clusters` on `fi.Client` (Python) and `client.errorClusters` on `Client` from `@future-agi/sdk` (TypeScript). The models these methods return are on [Observability response models](/docs/sdk/reference/observability-models); how arguments, pagination, errors and strict mode work is in the [overview](/docs/sdk/reference). ## Methods +
+ | Method | Description | |---|---| | [`error_clusters.get`](#error_clustersget) | Return an error issue and its grouped trace information. | | [`error_clusters.list`](#error_clusterslist) | List grouped error issues detected in project traces. | +| [`error_clusters.list_traces`](#error_clusterslist_traces) | List the traces grouped into a cluster with each one's score, latency, tokens and cost, alongside cluster-wide aggregates. | +| [`error_clusters.overview`](#error_clustersoverview) | Return a cluster's pattern summary (the statistical insights that separate its failing traces from the passing baseline), its daily error counts, and representative traces with their evidence and agent flow. | + +
## client.error_clusters @@ -148,3 +154,112 @@ export interface ErrorClustersListParams { #### Returns [`FeedListResponse`](/docs/sdk/reference/observability-models#feedlistresponse). + +### error_clusters.list_traces + +List the traces grouped into a cluster with each one's score, latency, tokens and cost, alongside cluster-wide aggregates. + + + +**MCP tool**: `list_error_cluster_traces` + + + +```python Python +result = client.error_clusters.list_traces("your-cluster-id") +``` + +```typescript TypeScript +const result = await client.errorClusters.listTraces("your-cluster-id"); +``` + + + + + +```python Python +client.error_clusters.list_traces( + cluster_id: str, + *, + limit: int | None | NotGiven = NOT_GIVEN, + offset: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.TracesTabResponse +``` + +```typescript TypeScript +client.errorClusters.listTraces(clusterId: string, params: ErrorClustersListTracesParams = {}, options?: RequestOptions): Promise + +export interface ErrorClustersListTracesParams { + limit?: number | null; + offset?: number | null; +} +``` + + + +#### Parameters + + + Positional argument `cluster_id`. + + + + +#### Returns + +[`TracesTabResponse`](/docs/sdk/reference/observability-models#tracestabresponse). + +### error_clusters.overview + +Return a cluster's pattern summary (the statistical insights that separate its failing traces from the passing baseline), its daily error counts, and representative traces with their evidence and agent flow. Representative traces carry inputs, outputs and conversation reels, so start with a small `rep_limit`. + + + +**MCP tool**: `get_error_cluster_overview` + + + +```python Python +result = client.error_clusters.overview("your-cluster-id") +``` + +```typescript TypeScript +const result = await client.errorClusters.overview("your-cluster-id"); +``` + + + + + +```python Python +client.error_clusters.overview( + cluster_id: str, + *, + rep_limit: int | None | NotGiven = NOT_GIVEN, + extra_query: dict[str, Any] | None = None, + options: RequestOptions | None = None, +) -> models.OverviewResponse +``` + +```typescript TypeScript +client.errorClusters.overview(clusterId: string, params: ErrorClustersOverviewParams = {}, options?: RequestOptions): Promise + +export interface ErrorClustersOverviewParams { + rep_limit?: number | null; +} +``` + + + +#### Parameters + + + Positional argument `cluster_id`. + + + +#### Returns + +[`OverviewResponse`](/docs/sdk/reference/observability-models#overviewresponse). diff --git a/src/pages/docs/sdk/reference/evals.mdx b/src/pages/docs/sdk/reference/evals.mdx index 3a2761deb..b065b8b7b 100644 --- a/src/pages/docs/sdk/reference/evals.mdx +++ b/src/pages/docs/sdk/reference/evals.mdx @@ -7,6 +7,8 @@ description: "Reference for client.evals in the Future AGI Python and TypeScript ## Methods +
+ | Method | Description | |---|---| | [`evals.test`](#evalstest) | Execute an evaluation template against supplied test inputs. | @@ -25,6 +27,8 @@ description: "Reference for client.evals in the Future AGI Python and TypeScript | [`evals.templates.list`](#evalstemplateslist) | List evaluation templates using the supplied filters. | | [`evals.templates.update`](#evalstemplatesupdate) | Update an existing evaluation template. | +
+ ## client.evals ### evals.test diff --git a/src/pages/docs/sdk/reference/experiments.mdx b/src/pages/docs/sdk/reference/experiments.mdx index 00da2c8d9..b279328b9 100644 --- a/src/pages/docs/sdk/reference/experiments.mdx +++ b/src/pages/docs/sdk/reference/experiments.mdx @@ -7,12 +7,16 @@ description: "Reference for client.experiments in the Future AGI Python and Type ## Methods +
+ | Method | Description | |---|---| | [`experiments.create`](#experimentscreate) | Create and start an experiment. | | [`experiments.get`](#experimentsget) | Return an experiment by its identifier. | | [`experiments.list`](#experimentslist) | List experiments in the current workspace. | +
+ ## client.experiments ### experiments.create diff --git a/src/pages/docs/sdk/reference/file-knowledge-bases.mdx b/src/pages/docs/sdk/reference/file-knowledge-bases.mdx index 9aaa849f1..ef68ff786 100644 --- a/src/pages/docs/sdk/reference/file-knowledge-bases.mdx +++ b/src/pages/docs/sdk/reference/file-knowledge-bases.mdx @@ -7,6 +7,8 @@ description: "Reference for client.file_knowledge_bases in the Future AGI Python ## Methods +
+ | Method | Description | |---|---| | [`file_knowledge_bases.create`](#file_knowledge_basescreate) | Create a file knowledge base (the Knowledge Base page of the app), optionally uploading its first files (pdf, docx, txt, rtf). | @@ -17,6 +19,8 @@ description: "Reference for client.file_knowledge_bases in the Future AGI Python | [`file_knowledge_bases.files.delete`](#file_knowledge_basesfilesdelete) | Delete files from a file knowledge base, by id or name, or all of them. | | [`file_knowledge_bases.files.list`](#file_knowledge_basesfileslist) | List the files in a file knowledge base, with their processing status. | +
+ ## client.file_knowledge_bases ### file_knowledge_bases.create diff --git a/src/pages/docs/sdk/reference/gateway-models.mdx b/src/pages/docs/sdk/reference/gateway-models.mdx index 39cdcdcbe..d18fba6b8 100644 --- a/src/pages/docs/sdk/reference/gateway-models.mdx +++ b/src/pages/docs/sdk/reference/gateway-models.mdx @@ -3,10 +3,12 @@ title: "Gateway response models" description: "The 8 response models returned by the gateway resources of the Future AGI Python and TypeScript SDKs, with every field and its type." --- -The models returned by `client.gateway`, `client.models`, `client.provider_keys`, 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)). +The models returned by `client.gateway`, `client.models`, `client.provider_keys`, 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. ## Models +
+ | Model | Fields | |---|---| | `AgentccRequestLog` | `id: string`, `request_id: string`, `model: string`, `provider: string`, `resolved_model: string`, `latency_ms: integer`, `started_at: string`, `input_tokens: integer`, `output_tokens: integer`, `total_tokens: integer`, `cost: string`, `status_code: integer`, `is_stream: boolean`, `is_error: boolean`, `error_message: string`, `cache_hit: boolean`, `fallback_used: boolean`, `guardrail_triggered: boolean`, `api_key_id: string`, `user_id: string`, `session_id: string`, `routing_strategy: string`, `metadata: any`, `organization: string`, `workspace: string`, `created_at: string` | @@ -17,3 +19,5 @@ The models returned by `client.gateway`, `client.models`, `client.provider_keys` | `GatewayStatus` | `status: string` | | `GatewaySummaryResult` | `id: string`, `name: string`, `base_url: string`, `status: string`, `provider_count: integer`, `model_count: integer` | | `ModelHubPaginatedResponse` | `count: integer`, `next: string`, `previous: string`, `results: any[]` | + +
diff --git a/src/pages/docs/sdk/reference/gateway.mdx b/src/pages/docs/sdk/reference/gateway.mdx index 8a304ec06..b588c6ce6 100644 --- a/src/pages/docs/sdk/reference/gateway.mdx +++ b/src/pages/docs/sdk/reference/gateway.mdx @@ -7,6 +7,8 @@ description: "Reference for client.gateway in the Future AGI Python and TypeScri ## Methods +
+ | Method | Description | |---|---| | [`gateway.analytics`](#gatewayanalytics) | Return overview usage, latency, error, and cost analytics for the AI gateway. | @@ -17,6 +19,8 @@ description: "Reference for client.gateway in the Future AGI Python and TypeScri | [`gateway.sessions.list`](#gatewaysessionslist) | List AI gateway sessions with their stats. | | [`gateway.sessions.requests`](#gatewaysessionsrequests) | List every request log belonging to one gateway session. | +
+ ## client.gateway ### gateway.analytics diff --git a/src/pages/docs/sdk/reference/index.mdx b/src/pages/docs/sdk/reference/index.mdx index 28d8ae5a6..d9f645f71 100644 --- a/src/pages/docs/sdk/reference/index.mdx +++ b/src/pages/docs/sdk/reference/index.mdx @@ -5,7 +5,7 @@ description: "Every method of the Future AGI platform client in Python and TypeS - One client, every API: `fi.Client` (Python, `pip install futureagi`) and `Client` from `@future-agi/sdk` (TypeScript) -- 162 methods across 25 resources, generated from the API contract; each page lists parameters, return types and the REST endpoint +- 164 methods across 25 resources, generated from the API contract; each page lists parameters, return types and the REST endpoint - Omitted arguments are not sent, `None` / `null` is; list calls return pagers; HTTP errors raise typed exceptions @@ -94,7 +94,19 @@ Responses are parsed into models (`fi.platform.models` / `@future-agi/sdk/platfo ### Errors -HTTP errors raise a subclass of `APIError` (`fi.platform` / `@future-agi/sdk`) with `status_code` / `status`, `body`, `detail` and `request_id` / `requestId`: +HTTP errors raise a subclass of `APIError` with `status_code` / `status`, `body`, `detail` and `request_id` / `requestId`. Import the error classes from `fi.platform` (Python) and from **`@future-agi/sdk/platform`** (TypeScript): the package root does not export them, and its `RateLimitError` is an older, unrelated class that an `instanceof` check against platform errors never matches. + + +```python Python +from fi.platform import APIError, NotFoundError, RateLimitError +``` + +```typescript TypeScript +import { APIError, NotFoundError, RateLimitError } from "@future-agi/sdk/platform"; +``` + + +
| Status | Error | |---|---| @@ -108,6 +120,8 @@ HTTP errors raise a subclass of `APIError` (`fi.platform` / `@future-agi/sdk`) w | 429 | `RateLimitError` | | 5xx | `InternalServerError` | +
+ Network failures raise `APIConnectionError`. All of them extend `FutureAGIError`. ### Stability @@ -187,7 +201,7 @@ A method marked **Beta** may change without notice; the first call emits a `Beta `client.dashboards`: 13 methods. - `client.error_clusters`: 2 methods. + `client.error_clusters`: 4 methods. `client.alerts`: 2 methods. diff --git a/src/pages/docs/sdk/reference/knowledge-bases-models.mdx b/src/pages/docs/sdk/reference/knowledge-bases-models.mdx index 2d6bb74c4..6353f7c7d 100644 --- a/src/pages/docs/sdk/reference/knowledge-bases-models.mdx +++ b/src/pages/docs/sdk/reference/knowledge-bases-models.mdx @@ -3,10 +3,12 @@ title: "Knowledge bases response models" description: "The 10 response models returned by the knowledge bases resources of the Future AGI Python and TypeScript SDKs, with every field and its type." --- -The models returned by `client.knowledge_bases`, `client.file_knowledge_bases`, 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)). +The models returned by `client.knowledge_bases`, `client.file_knowledge_bases`, 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. ## Models +
+ | Model | Fields | |---|---| | `KnowledgeBaseItem` | `id: string`, `name: string`, `embedding_model: string`, `chunk_size: integer`, `organization: string`, `created_at: string`, `updated_at: string` | @@ -19,3 +21,5 @@ The models returned by `client.knowledge_bases`, `client.file_knowledge_bases`, | `LegacyKnowledgeBaseTableColumn` | `id: string`, `name: string` | | `LegacyKnowledgeBaseTableResult` | `column_config:` [`LegacyKnowledgeBaseTableColumn`](#legacyknowledgebasetablecolumn)[], `table_data:` [`LegacyKnowledgeBaseTableRow`](#legacyknowledgebasetablerow)[], `total_rows: integer` | | `LegacyKnowledgeBaseTableRow` | `id: string`, `name: string`, `files_uploaded: integer`, `status: string`, `error: string`, `updated_at: string`, `created_by: string` | + +
diff --git a/src/pages/docs/sdk/reference/knowledge-bases.mdx b/src/pages/docs/sdk/reference/knowledge-bases.mdx index 359db748c..027eb385c 100644 --- a/src/pages/docs/sdk/reference/knowledge-bases.mdx +++ b/src/pages/docs/sdk/reference/knowledge-bases.mdx @@ -7,6 +7,8 @@ description: "Reference for client.knowledge_bases in the Future AGI Python and ## Methods +
+ | Method | Description | |---|---| | [`knowledge_bases.create`](#knowledge_basescreate) | Create a knowledge base with a name, an embedding model and a chunk size; it appears in knowledge_bases.list and knowledge_bases.get. | @@ -15,6 +17,8 @@ description: "Reference for client.knowledge_bases in the Future AGI Python and | [`knowledge_bases.list`](#knowledge_baseslist) | List knowledge bases (the RAG stores with an embedding model and a chunk size) in the current workspace. | | [`knowledge_bases.update`](#knowledge_basesupdate) | Update the name, embedding model or chunk size of a knowledge base (a partial update). | +
+ ## client.knowledge_bases ### knowledge_bases.create diff --git a/src/pages/docs/sdk/reference/models.mdx b/src/pages/docs/sdk/reference/models.mdx index 19e384757..589a34b7e 100644 --- a/src/pages/docs/sdk/reference/models.mdx +++ b/src/pages/docs/sdk/reference/models.mdx @@ -7,10 +7,14 @@ description: "Reference for client.models in the Future AGI Python and TypeScrip ## Methods +
+ | Method | Description | |---|---| | [`models.list`](#modelslist) | List the LLM models available to prompts and evaluations, with their providers. | +
+ ## client.models ### models.list diff --git a/src/pages/docs/sdk/reference/observability-models.mdx b/src/pages/docs/sdk/reference/observability-models.mdx index 0ad92c262..ac45583e4 100644 --- a/src/pages/docs/sdk/reference/observability-models.mdx +++ b/src/pages/docs/sdk/reference/observability-models.mdx @@ -1,14 +1,17 @@ --- title: "Observability response models" -description: "The 46 response models returned by the observability resources of the Future AGI Python and TypeScript SDKs, with every field and its type." +description: "The 59 response models returned by the observability resources of the Future AGI Python and TypeScript SDKs, with every field and its type." --- -The models returned by `client.projects`, `client.traces`, `client.spans`, `client.sessions`, `client.dashboards`, `client.error_clusters`, `client.alerts`, 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)). +The models returned by `client.projects`, `client.traces`, `client.spans`, `client.sessions`, `client.dashboards`, `client.error_clusters`, `client.alerts`, 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. ## Models +
+ | Model | Fields | |---|---| +| `AgentFlowGraph` | `nodes: any[]`, `edges: any[]` | | `Dashboard` | `id: string`, `name: string`, `description: string`, `workspace: string`, `created_by:` [`User`](#user), `updated_by:` [`User`](#user), `created_at: string`, `updated_at: string`, `widget_count: any` | | `DashboardDetail` | `id: string`, `name: string`, `description: string`, `workspace: string`, `created_by:` [`User`](#user), `updated_by:` [`User`](#user), `created_at: string`, `updated_at: string`, `widgets: any` | | `DashboardFilterValueOption` | `value: any JSON value`, `label: string`, `type: string`, `name: string`, `email: string`, `description: string` | @@ -25,20 +28,28 @@ The models returned by `client.projects`, `client.traces`, `client.spans`, `clie | `EvalRollup` | `scope: string`, `evals:` [`EvalRollupEval`](#evalrollupeval)[], `error: boolean` | | `EvalRollupEval` | `eval_config_id: string`, `eval_name: string`, `output_type: string`, `template_type: string`, `target_type: string`, `choices_map: any JSON value`, `aggregate: any JSON value`, `spans:` [`EvalRollupSpan`](#evalrollupspan)[], `error: boolean` | | `EvalRollupSpan` | `span_id: string`, `span_name: string`, `value: any JSON value`, `explanation: string`, `error: boolean`, `status: string`, `eval_config_id: string` | +| `EventsOverTimePoint` | `date: string`, `errors: integer`, `passing: integer`, `users: integer` | | `FeedDetailCore` | `row:` [`FeedListRow`](#feedlistrow), `description: string`, `success_trace:` [`TracePreview`](#tracepreview), `representative_trace:` [`TracePreview`](#tracepreview), `rca:` [`RcaSummary`](#rcasummary) | | `FeedListResponse` | `data:` [`FeedListRow`](#feedlistrow)[], `total: integer`, `limit: integer`, `offset: integer` | | `FeedListRow` | `severity_assessment_status: string`, `severity_source: string`, `severity_reason: string`, `cluster_id: string`, `source: string`, `modality: string`, `error:` [`ErrorName`](#errorname), `status: string`, `severity: string`, `occurrences: integer`, `trace_count: integer`, `fix_layer: string`, `users_affected: integer`, `sessions: integer`, `first_seen: string`, `last_seen: string`, `trends:` [`TrendPoint`](#trendpoint)[], `assignees: string[]`, `model: string`, `model_version: string`, `project: string`, `project_id: string`, `environment: string`, `eval_score: number`, `trace_id: string`, `external_issue_url: string`, `external_issue_id: string` | +| `KeyMoment` | `kevinified: string`, `verbatim: string` | | `ObservationSpanDetailResult` | `observation_span: any`, `evals_metrics: any`, `enrichment: any` | | `Organization` | `id: string`, `created_at: string`, `name: string`, `display_name: string`, `is_new: boolean`, `ws_enabled: boolean`, `region: string`, `require_2fa: boolean`, `require_2fa_grace_period_days: integer`, `require_2fa_enforced_at: string` | +| `OverviewResponse` | `events_over_time:` [`EventsOverTimePoint`](#eventsovertimepoint)[], `pattern_summary:` [`PatternSummary`](#patternsummary), `representative_traces:` [`RepresentativeTrace`](#representativetrace)[], `representative_total: integer` | +| `PatternInsight` | `title: string`, `value: string`, `caption: string`, `evidence:` [`PatternInsightEvidence`](#patterninsightevidence) | +| `PatternInsightEvidence` | `test: string`, `baseline: string`, `tool: string`, `z: number`, `p_value: number`, `ks_stat: number`, `fail_median: number`, `baseline_median: number`, `fail_pct: integer`, `baseline_pct: integer`, `hits: integer`, `total: integer`, `missing_in: integer`, `traces_with_tools: integer` | +| `PatternSummary` | `insights:` [`PatternInsight`](#patterninsight)[], `key_moments:` [`KeyMoment`](#keymoment)[] | | `ProjectDetailResult` | `id: string`, `model_type: string`, `name: string`, `trace_type: string`, `metadata: any`, `organization: string`, `workspace: string`, `created_at: string`, `updated_at: string`, `config: any JSON value`, `source: string`, `session_config: any JSON value`, `tags: any JSON value`, `sampling_rate: number` | | `RcaSummary` | `synthesis: string`, `fix: string`, `confidence: string`, `evidence_trace_ids: string[]`, `analyzed_at: string`, `failures_at_run: integer`, `trace:` [`RcaTrailStep`](#rcatrailstep)[] | | `RcaTrailStep` | `type: string`, `text: string`, `call_id: string`, `tool: string`, `args: any`, `result: any`, `synthesis: string`, `fix: string`, `confidence: string` | +| `RepresentativeTrace` | `id: string`, `status: string`, `timestamp: string`, `summary:` [`TraceSummary`](#tracesummary), `evidence:` [`TraceEvidence`](#traceevidence), `agent_flow:` [`AgentFlowGraph`](#agentflowgraph), `root_causes: any[]`, `recommendations: any[]`, `what_changed: any` | | `SpanListColumnConfig` | `id: string`, `name: string`, `is_visible: boolean`, `group_by: string`, `output_type: string`, `reverse_output: boolean`, `annotation_label_type: string`, `choices: string[]`, `settings: any JSON value`, `choices_map: any JSON value`, `eval_template_id: string`, `target_type: string`, `annotators: any JSON value`, `source_field: string`, `parent_eval_id: string`, `property_id: string`, `property_kind: string`, `property_source: string` | | `SpanListMetadata` | `total_rows: integer`, `total_rows_exact: integer`, `total_rows_is_lower_bound: boolean`, `has_more: boolean`, `next_cursor: string`, `next_cursor_fingerprint: string`, `query_complete: boolean`, `query_status: string`, `query_error_code: string`, `query_elapsed_ms: number`, `query_count: integer`, `query_rows_returned: integer`, `query_result_payload_bytes: integer`, `query_applied_filter_version: string`, `query_applied_filter_sha256: string`, `query_applied_filter_count: integer`, `query_exact: boolean`, `ordering_exact: boolean` | | `SpanObserveListResult` | `metadata:` [`SpanListMetadata`](#spanlistmetadata), `table: any[]`, `config:` [`SpanListColumnConfig`](#spanlistcolumnconfig)[] | | `TraceDetailResult` | `trace: any`, `observation_spans:` [`TraceDetailSpan`](#tracedetailspan)[], `summary: any`, `graph: any` | | `TraceDetailSpan` | `observation_span: any`, `children: any[]`, `eval_scores: any[]`, `eval_rollup:` [`EvalRollup`](#evalrollup), `annotations: any[]` | | `TraceErrorAnalysisResult` | `analysis_exists: boolean`, `trace_id: string`, `message: string`, `analysis_id: string`, `analysis_date: string`, `agent_version: string`, `memory_enhanced: boolean`, `summary: any`, `errors: any[]`, `grouped_errors: any[]`, `scores: any`, `memory_context: any` | +| `TraceEvidence` | `input: string`, `output: string`, `fail_reel: any[]`, `pass_reel: any[]`, `judge_reason: string`, `score: number` | | `TraceObserveColumnConfig` | `id: string`, `name: string`, `is_visible: boolean`, `group_by: string`, `output_type: string`, `reverse_output: boolean`, `annotation_label_type: string`, `choices: string[]`, `settings: any JSON value`, `choices_map: any JSON value`, `eval_template_id: string`, `target_type: string`, `annotators: any JSON value`, `source_field: string`, `parent_eval_id: string`, `property_id: string`, `property_kind: string`, `property_source: string` | | `TraceObserveListMetadata` | `total_rows: integer`, `total_rows_exact: integer`, `total_rows_is_lower_bound: boolean`, `has_more: boolean`, `next_cursor: string`, `next_cursor_fingerprint: string`, `query_complete: boolean`, `query_status: string`, `query_error_code: string`, `query_elapsed_ms: number`, `query_count: integer`, `query_rows_returned: integer`, `query_result_payload_bytes: integer`, `query_applied_filter_version: string`, `query_applied_filter_sha256: string`, `query_applied_filter_count: integer`, `query_exact: boolean`, `ordering_exact: boolean` | | `TraceObserveListResult` | `metadata:` [`TraceObserveListMetadata`](#traceobservelistmetadata), `table: any[]`, `config:` [`TraceObserveColumnConfig`](#traceobservecolumnconfig)[] | @@ -47,6 +58,10 @@ The models returned by `client.projects`, `client.traces`, `client.spans`, `clie | `TraceSessionListMetadata` | `total_rows: integer`, `total_rows_exact: integer`, `total_rows_is_lower_bound: boolean`, `has_more: boolean`, `next_cursor: string`, `next_cursor_fingerprint: string`, `query_complete: boolean`, `query_status: string`, `query_error_code: string`, `query_elapsed_ms: number`, `query_count: integer`, `query_rows_returned: integer`, `query_result_payload_bytes: integer`, `query_applied_filter_version: string`, `query_applied_filter_sha256: string`, `query_applied_filter_count: integer`, `query_exact: boolean`, `ordering_exact: boolean`, `query_provenance: string` | | `TraceSessionListResult` | `metadata:` [`TraceSessionListMetadata`](#tracesessionlistmetadata), `table:` [`TraceSessionTableRow`](#tracesessiontablerow)[], `config:` [`TraceObserveColumnConfig`](#traceobservecolumnconfig)[] | | `TraceSessionTableRow` | `session_id: string`, `session_name: string`, `project_id: string`, `start_time: string`, `end_time: string`, `created_at: string`, `duration: number`, `total_cost: number`, `total_tokens: integer`, `total_traces_count: integer`, `first_message: any JSON value`, `last_message: any JSON value`, `user_id: string`, `user_id_type: string`, `user_id_hash: string` | +| `TraceSummary` | `eval_score: number`, `latency_ms: integer`, `turns: integer`, `model: string`, `input_tokens: integer`, `output_tokens: integer` | +| `TracesAggregates` | `total_traces: integer`, `failing_traces: integer`, `passing_traces: integer`, `avg_score: number`, `p50_latency: integer`, `p95_latency: integer`, `avg_turns: number` | +| `TracesListRow` | `id: string`, `input: string`, `timestamp: string`, `latency_ms: integer`, `tokens: integer`, `cost: number`, `score: number`, `turns: integer` | +| `TracesTabResponse` | `aggregates:` [`TracesAggregates`](#tracesaggregates), `traces:` [`TracesListRow`](#traceslistrow)[], `total: integer` | | `TrendPoint` | `timestamp: string`, `value: integer`, `users: integer` | | `User` | `id: string`, `email: string`, `name: string`, `organization_role: string`, `organization:` [`Organization`](#organization), `created_at: string`, `status: any`, `role: string`, `goals: any` | | `UserAlertMonitorListColumn` | `id: string`, `name: string`, `is_visible: boolean` | @@ -55,3 +70,5 @@ The models returned by `client.projects`, `client.traces`, `client.spans`, `clie | `UserAlertMonitorListResult` | `column_config:` [`UserAlertMonitorListColumn`](#useralertmonitorlistcolumn)[], `table:` [`UserAlertMonitorListItem`](#useralertmonitorlistitem)[], `metadata:` [`UserAlertMonitorListMetadata`](#useralertmonitorlistmetadata) | | `UserAlertMonitorLog` | `id: string`, `resolved_by:` [`User`](#user), `created_at: string`, `type: string`, `message: string`, `resolved: boolean`, `resolved_at: string`, `link: string`, `time_window_start: string`, `time_window_end: string` | | `UserAlertMonitorTrend` | `timestamp: string`, `count: integer` | + +
diff --git a/src/pages/docs/sdk/reference/optimizations.mdx b/src/pages/docs/sdk/reference/optimizations.mdx index 50c4223b6..d7295c31b 100644 --- a/src/pages/docs/sdk/reference/optimizations.mdx +++ b/src/pages/docs/sdk/reference/optimizations.mdx @@ -7,12 +7,16 @@ description: "Reference for client.optimizations in the Future AGI Python and Ty ## Methods +
+ | Method | Description | |---|---| | [`optimizations.create`](#optimizationscreate) | Create a dataset optimization run. | | [`optimizations.get`](#optimizationsget) | Return a dataset optimization run by its identifier. | | [`optimizations.list`](#optimizationslist) | List dataset optimization runs. | +
+ ## client.optimizations ### optimizations.create diff --git a/src/pages/docs/sdk/reference/projects.mdx b/src/pages/docs/sdk/reference/projects.mdx index 426222285..7fe4a1f9d 100644 --- a/src/pages/docs/sdk/reference/projects.mdx +++ b/src/pages/docs/sdk/reference/projects.mdx @@ -7,11 +7,15 @@ description: "Reference for client.projects in the Future AGI Python and TypeScr ## Methods +
+ | Method | Description | |---|---| | [`projects.get`](#projectsget) | Return a tracing project by its identifier. | | [`projects.list`](#projectslist) | List tracing projects available in the current workspace. | +
+ ## client.projects ### projects.get diff --git a/src/pages/docs/sdk/reference/prompts-models.mdx b/src/pages/docs/sdk/reference/prompts-models.mdx index af30fdb6a..5e50f8fb8 100644 --- a/src/pages/docs/sdk/reference/prompts-models.mdx +++ b/src/pages/docs/sdk/reference/prompts-models.mdx @@ -3,10 +3,12 @@ title: "Prompts response models" description: "The 6 response models returned by the prompts resources of the Future AGI Python and TypeScript SDKs, with every field and its type." --- -The models returned by `client.prompts`, 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)). +The models returned by `client.prompts`, 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. ## Models +
+ | Model | Fields | |---|---| | `PromptHistoryExecution` | `id: string`, `template_version: string`, `output: any`, `prompt_config_snapshot: any`, `template_name: string`, `original_template: string`, `metadata: any`, `variable_names: any`, `evaluation_results: any`, `evaluation_configs: any`, `created_at: string`, `is_default: boolean`, `commit_message: string`, `updated_at: string`, `is_draft: boolean`, `labels: any`, `placeholders: any`, `prompt_base_template: string` | @@ -15,3 +17,5 @@ The models returned by `client.prompts`, importable from `fi.platform.models` (P | `PromptTemplate` | `id: string`, `name: string`, `description: string`, `variable_names: any`, `organization: string`, `prompt_folder: string`, `placeholders: any`, `created_by: string` | | `PromptTemplatePatch` | `id: string`, `name: string`, `description: string`, `variable_names: any`, `organization: string`, `prompt_folder: string`, `placeholders: any`, `created_by: string` | | `PromptsRunResult` | `template_id: string`, `prompt_config: any[]`, `variable_names: any`, `evaluation_configs: any[]`, `placeholders: any` | + +
diff --git a/src/pages/docs/sdk/reference/prompts.mdx b/src/pages/docs/sdk/reference/prompts.mdx index f1f2cfa96..3b06db443 100644 --- a/src/pages/docs/sdk/reference/prompts.mdx +++ b/src/pages/docs/sdk/reference/prompts.mdx @@ -7,6 +7,8 @@ description: "Reference for client.prompts in the Future AGI Python and TypeScri ## Methods +
+ | Method | Description | |---|---| | [`prompts.add_draft`](#promptsadd_draft) | Add new draft versions to a prompt template. | @@ -32,6 +34,8 @@ description: "Reference for client.prompts in the Future AGI Python and TypeScri | [`prompts.labels.set_default`](#promptslabelsset_default) | Make a version the default for a prompt template, by template name. | | [`prompts.versions.list`](#promptsversionslist) | List versions of a prompt template. | +
+ ## client.prompts ### prompts.add_draft diff --git a/src/pages/docs/sdk/reference/provider-keys.mdx b/src/pages/docs/sdk/reference/provider-keys.mdx index 604b6a2ff..7169af294 100644 --- a/src/pages/docs/sdk/reference/provider-keys.mdx +++ b/src/pages/docs/sdk/reference/provider-keys.mdx @@ -7,10 +7,14 @@ description: "Reference for client.provider_keys in the Future AGI Python and Ty ## Methods +
+ | Method | Description | |---|---| | [`provider_keys.list`](#provider_keyslist) | List the model-provider API keys configured for the organization (values are masked). | +
+ ## client.provider_keys ### provider_keys.list diff --git a/src/pages/docs/sdk/reference/scores.mdx b/src/pages/docs/sdk/reference/scores.mdx index c1eefb883..555240139 100644 --- a/src/pages/docs/sdk/reference/scores.mdx +++ b/src/pages/docs/sdk/reference/scores.mdx @@ -7,12 +7,16 @@ description: "Reference for client.scores in the Future AGI Python and TypeScrip ## Methods +
+ | Method | Description | |---|---| | [`scores.create`](#scorescreate) | Record one score (annotation value) against a source such as a span or dataset row. | | [`scores.create_bulk`](#scorescreate_bulk) | Record several scores against one source in a single call. | | [`scores.list_for_source`](#scoreslist_for_source) | List the scores recorded against one source. | +
+ ## client.scores ### scores.create diff --git a/src/pages/docs/sdk/reference/sessions.mdx b/src/pages/docs/sdk/reference/sessions.mdx index 6bd7c73f6..faf3a786b 100644 --- a/src/pages/docs/sdk/reference/sessions.mdx +++ b/src/pages/docs/sdk/reference/sessions.mdx @@ -7,11 +7,15 @@ description: "Reference for client.sessions in the Future AGI Python and TypeScr ## Methods +
+ | Method | Description | |---|---| | [`sessions.get`](#sessionsget) | Return a trace session by its identifier. | | [`sessions.list`](#sessionslist) | List trace sessions using the supplied filters. | +
+ ## client.sessions ### sessions.get diff --git a/src/pages/docs/sdk/reference/simulation-models.mdx b/src/pages/docs/sdk/reference/simulation-models.mdx index 217b254db..cfdd6e360 100644 --- a/src/pages/docs/sdk/reference/simulation-models.mdx +++ b/src/pages/docs/sdk/reference/simulation-models.mdx @@ -3,10 +3,12 @@ title: "Simulation response models" description: "The 20 response models returned by the simulation resources of the Future AGI Python and TypeScript SDKs, with every field and its type." --- -The models returned by `client.agents`, `client.simulation`, 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)). +The models returned by `client.agents`, `client.simulation`, 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. ## Models +
+ | Model | Fields | |---|---| | `AgentDefinitionCreateResponse` | `message: string`, `agent:` [`AgentDefinitionResponse`](#agentdefinitionresponse) | @@ -29,3 +31,5 @@ The models returned by `client.agents`, `client.simulation`, importable from `fi | `SimulateEvalConfigResponse` | `id: string`, `name: string`, `config: any`, `mapping: any`, `filters: object[]`, `error_localizer: boolean`, `model: string`, `status: string`, `eval_group: string`, `template_id: string`, `eval_type: string`, `regradable: boolean`, `editable: boolean` | | `TestExecution` | `id: string`, `run_test: string`, `run_test_name: string`, `agent_definition_name: string`, `status: string`, `error_reason: string`, `started_at: string`, `completed_at: string`, `total_scenarios: integer`, `total_calls: integer`, `completed_calls: integer`, `failed_calls: integer`, `execution_metadata: any`, `duration_seconds: any`, `success_rate: any`, `calls:` [`CallExecution`](#callexecution)[], `created_at: string`, `scenario_ids: any`, `simulator_agent_name: string`, `simulator_agent_id: string`, `agent_definition_used_name: string`, `agent_definition_used_id: string`, `calls_attempted: any`, `calls_connected_percentage: any` | | `TestExecutionAnalytics` | `fail_rate_over_test_runs: any`, `evaluation_categories_over_test_runs: any`, `metadata: any` | + +
diff --git a/src/pages/docs/sdk/reference/simulation.mdx b/src/pages/docs/sdk/reference/simulation.mdx index da174dbce..b9fb0c6a0 100644 --- a/src/pages/docs/sdk/reference/simulation.mdx +++ b/src/pages/docs/sdk/reference/simulation.mdx @@ -7,6 +7,8 @@ description: "Reference for client.simulation in the Future AGI Python and TypeS ## Methods +
+ | Method | Description | |---|---| | [`simulation.executions.analytics`](#simulationexecutionsanalytics) | Return aggregated analytics for a simulation test execution. | @@ -21,6 +23,8 @@ description: "Reference for client.simulation in the Future AGI Python and TypeS | [`simulation.tests.list`](#simulationtestslist) | List saved simulation test configurations. | | [`simulation.tests.run`](#simulationtestsrun) | Start a saved simulation test asynchronously. | +
+ ## client.simulation ## client.simulation.executions diff --git a/src/pages/docs/sdk/reference/spans.mdx b/src/pages/docs/sdk/reference/spans.mdx index ebf86ab86..49216572d 100644 --- a/src/pages/docs/sdk/reference/spans.mdx +++ b/src/pages/docs/sdk/reference/spans.mdx @@ -7,11 +7,15 @@ description: "Reference for client.spans in the Future AGI Python and TypeScript ## Methods +
+ | Method | Description | |---|---| | [`spans.get`](#spansget) | Return an observation span by its identifier. | | [`spans.list`](#spanslist) | List observation spans using the supplied filters. | +
+ ## client.spans ### spans.get diff --git a/src/pages/docs/sdk/reference/traces.mdx b/src/pages/docs/sdk/reference/traces.mdx index 0c9d29581..cc5e0d286 100644 --- a/src/pages/docs/sdk/reference/traces.mdx +++ b/src/pages/docs/sdk/reference/traces.mdx @@ -7,6 +7,8 @@ description: "Reference for client.traces in the Future AGI Python and TypeScrip ## Methods +
+ | Method | Description | |---|---| | [`traces.error_analysis`](#traceserror_analysis) | Return the recorded error analysis for a trace. | @@ -14,6 +16,8 @@ description: "Reference for client.traces in the Future AGI Python and TypeScrip | [`traces.list`](#traceslist) | Search traces using project, time range, status, and attribute filters. | | [`traces.properties.list`](#tracespropertieslist) | Discover filter properties from the shared metrics catalog. | +
+ ## client.traces ### traces.error_analysis @@ -156,6 +160,7 @@ const result = await client.traces.list(); ```python Python client.traces.list( *, + sort_params: str | None | NotGiven = NOT_GIVEN, project_id: str | None | NotGiven = NOT_GIVEN, project_version_id: str | None | NotGiven = NOT_GIVEN, session_id: str | None | NotGiven = NOT_GIVEN, @@ -176,6 +181,7 @@ client.traces.list( client.traces.list(params: TracesListParams = {}, options?: RequestOptions): Promise export interface TracesListParams { + sort_params?: string | null; project_id?: string | null; project_version_id?: string | null; session_id?: string | null; @@ -198,6 +204,7 @@ export interface TracesListParams { #### Parameters + diff --git a/src/pages/docs/sdk/reference/usage.mdx b/src/pages/docs/sdk/reference/usage.mdx index 6edd61d83..7309b2dea 100644 --- a/src/pages/docs/sdk/reference/usage.mdx +++ b/src/pages/docs/sdk/reference/usage.mdx @@ -7,10 +7,14 @@ description: "Reference for client.usage in the Future AGI Python and TypeScript ## Methods +
+ | Method | Description | |---|---| | [`usage.overview`](#usageoverview) | Return the current organization's usage and cost overview. | +
+ ## client.usage ### usage.overview diff --git a/src/pages/docs/sdk/reference/workspaces.mdx b/src/pages/docs/sdk/reference/workspaces.mdx index 462c427e8..c9d1e261f 100644 --- a/src/pages/docs/sdk/reference/workspaces.mdx +++ b/src/pages/docs/sdk/reference/workspaces.mdx @@ -7,11 +7,15 @@ description: "Reference for client.workspaces in the Future AGI Python and TypeS ## Methods +
+ | Method | Description | |---|---| | [`workspaces.get`](#workspacesget) | Return a workspace by its identifier. | | [`workspaces.list`](#workspaceslist) | List workspaces available to the authenticated user. | +
+ ## client.workspaces ### workspaces.get diff --git a/src/styles/global.css b/src/styles/global.css index 1872c939f..a1c000e3e 100644 --- a/src/styles/global.css +++ b/src/styles/global.css @@ -336,6 +336,36 @@ code:not(pre code) { background: var(--color-bg-secondary); } + /* Generated SDK reference tables: a bounded horizontal scroller, so a long + method or model identifier scrolls inside the table instead of widening the + page on a phone. Nothing is clipped: the description column stays reachable. */ + .sdk-ref-table { + max-width: 100%; + overflow-x: auto; + -webkit-overflow-scrolling: touch; + margin: 1.5rem 0; + } + + .sdk-ref-table table { + margin: 0; + } + + .sdk-ref-table th, + .sdk-ref-table td { + vertical-align: top; + } + + .sdk-ref-table td:first-child code { + white-space: nowrap; + } + + /* A heading that is one long identifier (`### annotation_queues.items.import_annotations`) + may break anywhere rather than overflow a narrow viewport. */ + h3, + h4 { + overflow-wrap: anywhere; + } + /* Clickable eval names in tables */ td a, td a strong { From c887cc9867f7fd2de145a78884460fe6c3f05cd3 Mon Sep 17 00:00:00 2001 From: tanmaycode1 Date: Wed, 4 Nov 2026 18:32:43 +0530 Subject: [PATCH 4/7] ci: re-trigger PR checks after the GitHub incident (no run fired for 5b669581) From df0dd06237f49934f2f988592920b65266a215e9 Mon Sep 17 00:00:00 2001 From: tanmaycode1 Date: Thu, 5 Nov 2026 11:57:56 +0530 Subject: [PATCH 5/7] docs(sdk): make the reference PR's draft/ready state follow the events safely Review finding on #1106 (nik13): a candidate event arriving after the same version-pair PR was already marked ready rewrote the branch and the body and printed "(candidate, draft)" while the PR stayed ready for merge. The PR step moves into scripts/sdk-reference-pr.sh with explicit state rules: - An existing PR that is already ready belongs to a released revision the registries confirmed; a later candidate (or any draft decision) is a stale or reordered event and is ignored outright: no push, no title/body edit, no state change, a ::notice:: saying so, exit 0. - A ready decision promotes a draft with `gh pr ready`, and a failed promotion fails the run. The final state is read back from GitHub after every run and must match the decision, or the run fails; the printed state is the real one. - A no-op diff opens nothing and closes an open PR for the release; a preview is its own draft on its own branch. scripts/sdk-reference-pr.test.mjs runs the real script against a fake `gh` (a PR-state adapter on a JSON file) and a fake `git`, asserting PR state after candidate -> released -> stale candidate -> repeated released, the failed promotion, the no-diff close, the preview branch, and a missing variable. Part of npm run test:integrations (39 tests). --- .github/workflows/sdk-reference-sync.yml | 53 +------- package.json | 2 +- scripts/sdk-reference-pr.sh | 118 ++++++++++++++++ scripts/sdk-reference-pr.test.mjs | 166 +++++++++++++++++++++++ 4 files changed, 289 insertions(+), 50 deletions(-) create mode 100755 scripts/sdk-reference-pr.sh create mode 100644 scripts/sdk-reference-pr.test.mjs diff --git a/.github/workflows/sdk-reference-sync.yml b/.github/workflows/sdk-reference-sync.yml index 30de07a7d..7ac149177 100644 --- a/.github/workflows/sdk-reference-sync.yml +++ b/.github/workflows/sdk-reference-sync.yml @@ -95,52 +95,7 @@ jobs: STAGE: ${{ steps.release.outputs.stage }} PUBLISH: ${{ steps.release.outputs.publish }} SOURCE: ${{ github.event.client_payload.source || format('{0}/{1}/actions/runs/{2}', github.server_url, github.repository, github.run_id) }} - run: | - set -eu - short=${SHA:0:12} - sdk="https://github.com/future-agi/futureagi-sdk" - number=$(gh pr list --head "$BRANCH" --base main --state open --json number --jq '.[0].number // empty') - if git diff --quiet -- src/pages/docs/sdk/reference src/lib/sdk-reference.mjs; then - if [ -z "$number" ]; then - echo "main already carries the reference of futureagi-sdk@$short; nothing to open" - exit 0 - fi - gh pr close "$number" --comment "main already carries the reference generated by futureagi-sdk@$short; nothing left to merge." \ - --delete-branch - exit 0 - fi - git config user.name "futureagi-release-bot[bot]" - git config user.email "futureagi-release-bot[bot]@users.noreply.github.com" - git switch -c "$BRANCH" - git add src/pages/docs/sdk/reference src/lib/sdk-reference.mjs - git commit -q -m "docs(sdk): sync the platform SDK reference from futureagi-sdk@$short" \ - -m "Python $PY, TypeScript $TS, backend contract $BACKEND ($STAGE)." - # One branch per release: a retry or the candidate→released transition rewrites it. - git push --force origin "$BRANCH" - case "$STAGE" in - released) title="docs(sdk): platform SDK reference for python-v$PY / typescript-v$TS" - stage_note="**Released.** \`futureagi==$PY\` is on [PyPI](https://pypi.org/project/futureagi/$PY/) and \`@future-agi/sdk@$TS\` on [npm](https://www.npmjs.com/package/@future-agi/sdk/v/$TS); this PR is ready for review." ;; - candidate) title="docs(sdk): platform SDK reference for python-v$PY / typescript-v$TS (candidate)" - stage_note="**Candidate (draft).** The SDK release is prepared but \`futureagi==$PY\` and \`@future-agi/sdk@$TS\` are not both installable yet. The publish workflow re-dispatches once they are, and this PR is marked ready then. Do not merge before." ;; - *) title="docs(sdk): platform SDK reference preview of futureagi-sdk@$short" - stage_note="**Preview (draft).** Generated from \`$REF\`, which is not a published release. For looking only; the released PR for these versions is opened by the SDK publish workflow." ;; - esac - cat > "$RUNNER_TEMP/body.md" </dev/null - fi - if [ "$PUBLISH" = ready ]; then - gh pr ready "$number" 2>/dev/null || true - fi - echo "future-agi/docs#$number ($STAGE, $PUBLISH)" + # scripts/sdk-reference-pr.sh holds the state rules (a stale candidate event never + # downgrades or rewrites a released PR; a ready decision is verified, not assumed) + # and scripts/sdk-reference-pr.test.mjs runs it against a fake gh/git. + run: bash scripts/sdk-reference-pr.sh diff --git a/package.json b/package.json index c371ff42b..3b1821359 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "astro": "astro", "new-doc": "node scripts/new-doc.mjs", "audit-links": "node scripts/audit-links.mjs", - "test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/sdk-reference-release.test.mjs", + "test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/sdk-reference-release.test.mjs scripts/sdk-reference-pr.test.mjs", "test:integrations:browser": "node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs && node scripts/sdk-reference-mobile.cjs", "check:integrations": "tsc --allowJs --checkJs --noEmit --strict --types node --target ES2022 --module nodenext src/lib/integrations.mjs" }, diff --git a/scripts/sdk-reference-pr.sh b/scripts/sdk-reference-pr.sh new file mode 100755 index 000000000..cf779b125 --- /dev/null +++ b/scripts/sdk-reference-pr.sh @@ -0,0 +1,118 @@ +#!/usr/bin/env bash +# Open, update, finish or skip the docs PR for one SDK release, from the synced working tree. +# +# Called by .github/workflows/sdk-reference-sync.yml after scripts/sync-sdk-reference.mjs has +# written the pages, with the resolver's decision in the environment (see +# scripts/sdk-reference-release.mjs): SHA REF PY TS BACKEND BRANCH STAGE PUBLISH SOURCE. +# Needs `gh` (GH_TOKEN set) and `git`; scripts/sdk-reference-pr.test.mjs runs it against fakes. +# +# State rules, so that reordered or retried dispatch events cannot leave a PR in the wrong state: +# - PUBLISH=ready : the PR must end up ready for review. A draft is promoted; the promotion is +# verified, and a failure to promote fails this run. +# - PUBLISH=draft : a NEW PR is opened as a draft. An EXISTING PR that is already ready belongs +# to a released revision that the registries confirmed; a later candidate +# event is stale or reordered, so it is IGNORED: neither the branch, nor the +# title/body, nor the state change. The run says so and exits 0. +# - no diff vs main : nothing to open; an open PR for this release is closed (main carries it). +# Every state the script reports is read back from GitHub after acting, never assumed. +set -euo pipefail + +for var in SHA PY TS BACKEND BRANCH STAGE PUBLISH; do + [ -n "${!var:-}" ] || { echo "::error::$var is not set" >&2; exit 2; } +done +: "${REF:=$SHA}" +: "${SOURCE:=manual run}" +short=${SHA:0:12} +sdk="https://github.com/future-agi/futureagi-sdk" +pages="src/pages/docs/sdk/reference src/lib/sdk-reference.mjs" + +# The open PR for this release, if any: " " (isDraft) or empty. +existing() { + gh pr list --head "$BRANCH" --base main --state open --json number,isDraft \ + --jq '.[0] | select(. != null) | "\(.number) \(.isDraft)"' +} +state_of() { + gh pr view "$1" --json isDraft --jq '.isDraft' +} + +read -r number is_draft <<< "$(existing || true)" +number=${number:-} +is_draft=${is_draft:-} + +# shellcheck disable=SC2086 +if git diff --quiet -- $pages; then + if [ -z "$number" ]; then + echo "main already carries the reference of futureagi-sdk@$short; nothing to open" + exit 0 + fi + gh pr close "$number" --delete-branch \ + --comment "main already carries the reference generated by futureagi-sdk@$short; nothing left to merge." + echo "future-agi/docs#$number closed: main already carries this reference" + exit 0 +fi + +if [ "$PUBLISH" = draft ] && [ -n "$number" ] && [ "$is_draft" = false ]; then + echo "::notice::future-agi/docs#$number for python-v$PY / typescript-v$TS is already ready for review" \ + "(a released revision the registries confirmed); ignoring this stale $STAGE event for $short." \ + "Neither the branch nor the PR was changed." + echo "future-agi/docs#$number (unchanged: ready, stale $STAGE event ignored)" + exit 0 +fi + +git config user.name "futureagi-release-bot[bot]" +git config user.email "futureagi-release-bot[bot]@users.noreply.github.com" +git switch -c "$BRANCH" +# shellcheck disable=SC2086 +git add $pages +git commit -q -m "docs(sdk): sync the platform SDK reference from futureagi-sdk@$short" \ + -m "Python $PY, TypeScript $TS, backend contract $BACKEND ($STAGE)." +# One branch per release: a retry or the candidate -> released transition rewrites it. +git push --force origin "$BRANCH" + +case "$STAGE" in + released) + title="docs(sdk): platform SDK reference for python-v$PY / typescript-v$TS" + stage_note="**Released.** \`futureagi==$PY\` is on [PyPI](https://pypi.org/project/futureagi/$PY/) and \`@future-agi/sdk@$TS\` on [npm](https://www.npmjs.com/package/@future-agi/sdk/v/$TS); this PR is ready for review." ;; + candidate) + title="docs(sdk): platform SDK reference for python-v$PY / typescript-v$TS (candidate)" + stage_note="**Candidate (draft).** The SDK release is prepared but \`futureagi==$PY\` and \`@future-agi/sdk@$TS\` are not both installable yet. The publish workflow re-dispatches once they are, and this PR is marked ready then. Do not merge before." ;; + *) + title="docs(sdk): platform SDK reference preview of futureagi-sdk@$short" + stage_note="**Preview (draft).** Generated from \`$REF\`, which is not a published release. For looking only; the released PR for these versions is opened by the SDK publish workflow." ;; +esac + +body_file=$(mktemp) +trap 'rm -f "$body_file"' EXIT +cat > "$body_file" </dev/null + read -r number is_draft <<< "$(existing)" + [ -n "$number" ] || { echo "::error::the PR for $BRANCH was not created" >&2; exit 1; } +else + gh pr edit "$number" --title "$title" --body-file "$body_file" >/dev/null +fi + +# Make the real PR state match the decision, and prove it. +if [ "$PUBLISH" = ready ] && [ "$is_draft" = true ]; then + gh pr ready "$number" || { echo "::error::could not mark future-agi/docs#$number ready for review" >&2; exit 1; } +fi +final=$(state_of "$number") +want=false +[ "$PUBLISH" = draft ] && want=true +if [ "$final" != "$want" ]; then + echo "::error::future-agi/docs#$number isDraft=$final after this run, expected $want ($STAGE, $PUBLISH)" >&2 + exit 1 +fi +state=ready +[ "$final" = true ] && state=draft +echo "future-agi/docs#$number ($STAGE, $state)" diff --git a/scripts/sdk-reference-pr.test.mjs b/scripts/sdk-reference-pr.test.mjs new file mode 100644 index 000000000..0c060f485 --- /dev/null +++ b/scripts/sdk-reference-pr.test.mjs @@ -0,0 +1,166 @@ +// @ts-check +// Lifecycle tests for scripts/sdk-reference-pr.sh: the real script runs against a fake `gh` +// (a PR-state adapter persisted in a JSON file) and a fake `git`, so the assertions are on the +// PR state GitHub would hold after each event, not on the resolver's decision string. +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { test } from 'node:test'; +import { fileURLToPath } from 'node:url'; + +const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'sdk-reference-pr.sh'); + +/** The fake `gh`: every PR mutation the script may issue, on a JSON state file. */ +const FAKE_GH = `#!/usr/bin/env node +const fs = require('node:fs'); +const file = process.env.FAKE_PR_STATE; +const state = JSON.parse(fs.readFileSync(file, 'utf-8')); +const save = () => fs.writeFileSync(file, JSON.stringify(state, null, 1)); +const args = process.argv.slice(2); +const log = (line) => fs.appendFileSync(process.env.FAKE_LOG, line + '\\n'); +log('gh ' + args.join(' ')); +const [cmd, sub] = args; +const flag = (name) => { const i = args.indexOf(name); return i === -1 ? undefined : args[i + 1]; }; +const open = () => state.prs.filter((p) => p.state === 'open'); +if (cmd === 'pr' && sub === 'list') { + const head = flag('--head'); + const hits = open().filter((p) => p.head === head); + const jq = flag('--jq'); + const first = hits[0]; + if (jq && jq.includes('select(. != null)')) { if (first) process.stdout.write(first.number + ' ' + first.isDraft + '\\n'); process.exit(0); } + process.stdout.write(JSON.stringify(hits.map((p) => ({ number: p.number, isDraft: p.isDraft })))); + process.exit(0); +} +if (cmd === 'pr' && sub === 'create') { + const number = state.next++; + state.prs.push({ number, head: flag('--head'), state: 'open', isDraft: args.includes('--draft'), title: flag('--title') }); + save(); process.stdout.write('https://github.com/future-agi/docs/pull/' + number + '\\n'); process.exit(0); +} +const pr = state.prs.find((p) => String(p.number) === args[2]); +if (cmd === 'pr' && sub === 'view') { process.stdout.write(String(pr.isDraft) + '\\n'); process.exit(0); } +if (cmd === 'pr' && sub === 'edit') { pr.title = flag('--title'); pr.edits = (pr.edits || 0) + 1; save(); process.exit(0); } +if (cmd === 'pr' && sub === 'ready') { + if (process.env.FAKE_READY_FAILS === '1') { process.stderr.write('GraphQL: forbidden\\n'); process.exit(1); } + pr.isDraft = false; save(); process.exit(0); +} +if (cmd === 'pr' && sub === 'close') { pr.state = 'closed'; save(); process.exit(0); } +process.stderr.write('fake gh: unexpected ' + args.join(' ') + '\\n'); process.exit(64); +`; + +/** The fake `git`: `diff --quiet` answers from FAKE_DIFF, pushes are recorded, the rest is a no-op. */ +const FAKE_GIT = `#!/usr/bin/env node +const fs = require('node:fs'); +const args = process.argv.slice(2); +fs.appendFileSync(process.env.FAKE_LOG, 'git ' + args.join(' ') + '\\n'); +if (args[0] === 'diff' && args.includes('--quiet')) process.exit(process.env.FAKE_DIFF === '0' ? 0 : 1); +process.exit(0); +`; + +function harness() { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sdk-ref-pr-')); + const bin = path.join(dir, 'bin'); + fs.mkdirSync(bin); + fs.writeFileSync(path.join(bin, 'gh'), FAKE_GH, { mode: 0o755 }); + fs.writeFileSync(path.join(bin, 'git'), FAKE_GIT, { mode: 0o755 }); + const stateFile = path.join(dir, 'prs.json'); + const logFile = path.join(dir, 'calls.log'); + fs.writeFileSync(stateFile, JSON.stringify({ next: 100, prs: [] })); + fs.writeFileSync(logFile, ''); + const base = { SHA: 'a'.repeat(40), REF: 'python-v0.7.0', PY: '0.7.0', TS: '0.2.0', BACKEND: 'v1.58.0', SOURCE: 'test' }; + /** @param {{STAGE: string, PUBLISH: string, BRANCH?: string, SHA?: string, diff?: boolean, readyFails?: boolean}} ev */ + const run = (ev) => { + const env = { + ...process.env, ...base, SHA: ev.SHA ?? base.SHA, + BRANCH: ev.BRANCH ?? 'sdk-reference/python-v0.7.0-typescript-v0.2.0', + STAGE: ev.STAGE, PUBLISH: ev.PUBLISH, + PATH: `${bin}:${process.env.PATH}`, FAKE_PR_STATE: stateFile, FAKE_LOG: logFile, + FAKE_DIFF: ev.diff === false ? '0' : '1', FAKE_READY_FAILS: ev.readyFails ? '1' : '0', GH_TOKEN: 'fake', + }; + const result = spawnSync('bash', [SCRIPT], { env, encoding: 'utf-8' }); + return { status: result.status, out: result.stdout + result.stderr }; + }; + const prs = () => JSON.parse(fs.readFileSync(stateFile, 'utf-8')).prs; + const calls = () => fs.readFileSync(logFile, 'utf-8').trim().split('\n').filter(Boolean); + const resetLog = () => fs.writeFileSync(logFile, ''); + return { run, prs, calls, resetLog }; +} + +test('candidate opens a draft; released promotes the same PR and verifies it; repeats are idempotent', () => { + const h = harness(); + let r = h.run({ STAGE: 'candidate', PUBLISH: 'draft' }); + assert.equal(r.status, 0, r.out); + assert.deepEqual(h.prs().map((p) => [p.number, p.isDraft, p.state]), [[100, true, 'open']]); + assert.match(r.out, /#100 \(candidate, draft\)/); + + r = h.run({ STAGE: 'released', PUBLISH: 'ready' }); + assert.equal(r.status, 0, r.out); + assert.deepEqual(h.prs().map((p) => [p.number, p.isDraft, p.state]), [[100, false, 'open']], 'same PR, now ready'); + assert.match(r.out, /#100 \(released, ready\)/); + assert.ok(h.calls().some((c) => c === 'gh pr ready 100'), 'the promotion was issued'); + + h.resetLog(); + r = h.run({ STAGE: 'released', PUBLISH: 'ready' }); + assert.equal(r.status, 0, r.out); + assert.equal(h.prs().length, 1, 'a repeated released event opens no second PR'); + assert.ok(!h.calls().some((c) => c.startsWith('gh pr create')), 'no create on repeat'); + assert.ok(!h.calls().some((c) => c === 'gh pr ready 100'), 'no redundant promotion of a ready PR'); +}); + +test('a stale candidate after released is ignored: the ready PR keeps its state, branch and body', () => { + const h = harness(); + assert.equal(h.run({ STAGE: 'candidate', PUBLISH: 'draft' }).status, 0); + assert.equal(h.run({ STAGE: 'released', PUBLISH: 'ready' }).status, 0); + h.resetLog(); + const r = h.run({ STAGE: 'candidate', PUBLISH: 'draft', SHA: 'b'.repeat(40) }); + assert.equal(r.status, 0, r.out); + assert.deepEqual(h.prs().map((p) => [p.number, p.isDraft]), [[100, false]], 'still ready'); + assert.match(r.out, /stale candidate event ignored/); + assert.match(r.out, /::notice::/); + const calls = h.calls(); + assert.ok(!calls.some((c) => c.startsWith('git push')), 'the released branch was not rewritten'); + assert.ok(!calls.some((c) => c.startsWith('gh pr edit')), 'the released title/body were not rewritten'); + assert.ok(!calls.some((c) => c.startsWith('gh pr ready') || c.startsWith('gh pr create'))); +}); + +test('a failed promotion fails the run instead of reporting ready', () => { + const h = harness(); + assert.equal(h.run({ STAGE: 'candidate', PUBLISH: 'draft' }).status, 0); + const r = h.run({ STAGE: 'released', PUBLISH: 'ready', readyFails: true }); + assert.notEqual(r.status, 0, 'must not exit 0'); + assert.match(r.out, /could not mark future-agi\/docs#100 ready/); + assert.deepEqual(h.prs().map((p) => p.isDraft), [true], 'the PR is honestly still a draft'); +}); + +test('no diff against main: nothing is opened, and an open PR for the release is closed', () => { + const h = harness(); + let r = h.run({ STAGE: 'released', PUBLISH: 'ready', diff: false }); + assert.equal(r.status, 0, r.out); + assert.equal(h.prs().length, 0); + assert.match(r.out, /nothing to open/); + assert.equal(h.run({ STAGE: 'candidate', PUBLISH: 'draft' }).status, 0); + r = h.run({ STAGE: 'released', PUBLISH: 'ready', diff: false }); + assert.equal(r.status, 0, r.out); + assert.deepEqual(h.prs().map((p) => p.state), ['closed']); +}); + +test('a preview is its own draft PR on its own branch and never touches a release PR', () => { + const h = harness(); + assert.equal(h.run({ STAGE: 'released', PUBLISH: 'ready' }).status, 0); + const r = h.run({ STAGE: 'preview', PUBLISH: 'draft', BRANCH: 'sdk-reference/preview-bbbbbbbbbbbb', SHA: 'b'.repeat(40) }); + assert.equal(r.status, 0, r.out); + assert.deepEqual(h.prs().map((p) => [p.head, p.isDraft]), [ + ['sdk-reference/python-v0.7.0-typescript-v0.2.0', false], + ['sdk-reference/preview-bbbbbbbbbbbb', true], + ]); + assert.match(r.out, /#101 \(preview, draft\)/); +}); + +test('a missing decision variable is a usage error, not a half-run', () => { + const h = harness(); + const r = h.run({ STAGE: 'released', PUBLISH: '' }); + assert.equal(r.status, 2); + assert.match(r.out, /PUBLISH is not set/); + assert.equal(h.prs().length, 0); +}); From 9e9bcbec9b3a8586c8f7c58eb7fb7fec4238d67a Mon Sep 17 00:00:00 2001 From: tanmaycode1 Date: Thu, 5 Nov 2026 12:13:46 +0530 Subject: [PATCH 6/7] ci: re-trigger PR checks (no run was scheduled for df0dd062) From e0bb648b136012d71b3fe9a5291ccfe122b26449 Mon Sep 17 00:00:00 2001 From: Tanmay Arora Date: Tue, 10 Nov 2026 03:06:03 +0530 Subject: [PATCH 7/7] docs(sdk): fail closed on a PR lookup error, guard stale candidates before cleanup, follow both release streams Review findings on #1106 (nik13), third round. - A failing `gh pr list` (a 502, say) used to read as "no PR", so a candidate could force-push over a ready release branch and only then fail on the duplicate create. The lookup is now captured in its own assignment and a failure stops the run before any git or PR mutation. - The ready-PR / stale-candidate rule now runs before the no-diff cleanup, so a stale candidate whose pages happen to match main can no longer close the ready PR and delete its released branch; it is ignored like any other stale event. - The scheduled default considered only python-v* tags. The SDK versions and publishes Python and TypeScript independently, so a TypeScript-only release was invisible and an older Python-tag commit could be proposed over newer pages. newestRelease() takes the newest tag of each stream, resolves both to commits and keeps the later commit; one stream alone is still a release, none fails closed. Registry checks are unchanged. Tests: lookup failure (no push, no create/edit/close, released PR still ready); ready + stale candidate + no diff (no close, no push, PR unchanged); a newer TypeScript-only release at commit B wins over the newest Python tag at A, and the reverse; single-stream and no-stream cases. 298 integration tests pass. --- scripts/sdk-reference-pr.sh | 29 ++++++++---- scripts/sdk-reference-pr.test.mjs | 31 +++++++++++- scripts/sdk-reference-release.mjs | 65 +++++++++++++++++++++----- scripts/sdk-reference-release.test.mjs | 29 ++++++++++-- 4 files changed, 129 insertions(+), 25 deletions(-) diff --git a/scripts/sdk-reference-pr.sh b/scripts/sdk-reference-pr.sh index cf779b125..a7c4c5408 100755 --- a/scripts/sdk-reference-pr.sh +++ b/scripts/sdk-reference-pr.sh @@ -14,6 +14,8 @@ # event is stale or reordered, so it is IGNORED: neither the branch, nor the # title/body, nor the state change. The run says so and exits 0. # - no diff vs main : nothing to open; an open PR for this release is closed (main carries it). +# Evaluated AFTER the stale-event rule, so an ignored event closes nothing. +# - lookup failure : if GitHub cannot say whether a PR exists, stop before any mutation. # Every state the script reports is read back from GitHub after acting, never assumed. set -euo pipefail @@ -35,10 +37,27 @@ state_of() { gh pr view "$1" --json isDraft --jq '.isDraft' } -read -r number is_draft <<< "$(existing || true)" +# Fail closed if the lookup itself fails: an API error must never look like "no PR", +# or a candidate could overwrite a released branch. Captured in its own assignment so +# `read` cannot mask the exit status. +if ! lookup=$(existing); then + echo "::error::could not look up the open PR for $BRANCH (gh pr list failed); nothing was changed" >&2 + exit 1 +fi +read -r number is_draft <<< "$lookup" number=${number:-} is_draft=${is_draft:-} +# A ready PR belongs to a released revision the registries confirmed. Decide this FIRST: +# an ignored stale event must not be able to close, delete or rewrite anything below. +if [ "$PUBLISH" = draft ] && [ -n "$number" ] && [ "$is_draft" = false ]; then + echo "::notice::future-agi/docs#$number for python-v$PY / typescript-v$TS is already ready for review" \ + "(a released revision the registries confirmed); ignoring this stale $STAGE event for $short." \ + "Neither the branch nor the PR was changed." + echo "future-agi/docs#$number (unchanged: ready, stale $STAGE event ignored)" + exit 0 +fi + # shellcheck disable=SC2086 if git diff --quiet -- $pages; then if [ -z "$number" ]; then @@ -51,14 +70,6 @@ if git diff --quiet -- $pages; then exit 0 fi -if [ "$PUBLISH" = draft ] && [ -n "$number" ] && [ "$is_draft" = false ]; then - echo "::notice::future-agi/docs#$number for python-v$PY / typescript-v$TS is already ready for review" \ - "(a released revision the registries confirmed); ignoring this stale $STAGE event for $short." \ - "Neither the branch nor the PR was changed." - echo "future-agi/docs#$number (unchanged: ready, stale $STAGE event ignored)" - exit 0 -fi - git config user.name "futureagi-release-bot[bot]" git config user.email "futureagi-release-bot[bot]@users.noreply.github.com" git switch -c "$BRANCH" diff --git a/scripts/sdk-reference-pr.test.mjs b/scripts/sdk-reference-pr.test.mjs index 0c060f485..80094ff3c 100644 --- a/scripts/sdk-reference-pr.test.mjs +++ b/scripts/sdk-reference-pr.test.mjs @@ -25,6 +25,7 @@ const [cmd, sub] = args; const flag = (name) => { const i = args.indexOf(name); return i === -1 ? undefined : args[i + 1]; }; const open = () => state.prs.filter((p) => p.state === 'open'); if (cmd === 'pr' && sub === 'list') { + if (process.env.FAKE_LIST_FAILS === '1') { process.stderr.write('HTTP 502: Bad Gateway\\n'); process.exit(1); } const head = flag('--head'); const hits = open().filter((p) => p.head === head); const jq = flag('--jq'); @@ -69,14 +70,14 @@ function harness() { fs.writeFileSync(stateFile, JSON.stringify({ next: 100, prs: [] })); fs.writeFileSync(logFile, ''); const base = { SHA: 'a'.repeat(40), REF: 'python-v0.7.0', PY: '0.7.0', TS: '0.2.0', BACKEND: 'v1.58.0', SOURCE: 'test' }; - /** @param {{STAGE: string, PUBLISH: string, BRANCH?: string, SHA?: string, diff?: boolean, readyFails?: boolean}} ev */ + /** @param {{STAGE: string, PUBLISH: string, BRANCH?: string, SHA?: string, diff?: boolean, readyFails?: boolean, listFails?: boolean}} ev */ const run = (ev) => { const env = { ...process.env, ...base, SHA: ev.SHA ?? base.SHA, BRANCH: ev.BRANCH ?? 'sdk-reference/python-v0.7.0-typescript-v0.2.0', STAGE: ev.STAGE, PUBLISH: ev.PUBLISH, PATH: `${bin}:${process.env.PATH}`, FAKE_PR_STATE: stateFile, FAKE_LOG: logFile, - FAKE_DIFF: ev.diff === false ? '0' : '1', FAKE_READY_FAILS: ev.readyFails ? '1' : '0', GH_TOKEN: 'fake', + FAKE_DIFF: ev.diff === false ? '0' : '1', FAKE_READY_FAILS: ev.readyFails ? '1' : '0', FAKE_LIST_FAILS: ev.listFails ? '1' : '0', GH_TOKEN: 'fake', }; const result = spawnSync('bash', [SCRIPT], { env, encoding: 'utf-8' }); return { status: result.status, out: result.stdout + result.stderr }; @@ -124,6 +125,32 @@ test('a stale candidate after released is ignored: the ready PR keeps its state, assert.ok(!calls.some((c) => c.startsWith('gh pr ready') || c.startsWith('gh pr create'))); }); +test('a failed PR lookup stops before any mutation: no push, no create, no edit, no close', () => { + const h = harness(); + assert.equal(h.run({ STAGE: 'released', PUBLISH: 'ready' }).status, 0); + h.resetLog(); + const r = h.run({ STAGE: 'candidate', PUBLISH: 'draft', SHA: 'b'.repeat(40), listFails: true }); + assert.notEqual(r.status, 0, 'a lookup error must not be read as "no PR"'); + assert.match(r.out, /could not look up the open PR/); + const calls = h.calls(); + assert.ok(!calls.some((c) => c.startsWith('git push') || c.startsWith('git switch') || c.startsWith('git commit')), 'branch untouched'); + assert.ok(!calls.some((c) => /^gh pr (create|edit|close|ready)/.test(c)), 'PR untouched'); + assert.deepEqual(h.prs().map((p) => [p.number, p.isDraft, p.state]), [[100, false, 'open']], 'the released PR is still ready'); +}); + +test('a stale candidate whose pages match main cannot close or delete the ready release PR', () => { + const h = harness(); + assert.equal(h.run({ STAGE: 'released', PUBLISH: 'ready' }).status, 0); + h.resetLog(); + const r = h.run({ STAGE: 'candidate', PUBLISH: 'draft', SHA: 'b'.repeat(40), diff: false }); + assert.equal(r.status, 0, r.out); + assert.match(r.out, /stale candidate event ignored/); + const calls = h.calls(); + assert.ok(!calls.some((c) => c.startsWith('gh pr close')), 'the no-diff cleanup did not run'); + assert.ok(!calls.some((c) => c.startsWith('git push')), 'the released branch was not touched'); + assert.deepEqual(h.prs().map((p) => [p.number, p.isDraft, p.state]), [[100, false, 'open']], 'released PR open and ready'); +}); + test('a failed promotion fails the run instead of reporting ready', () => { const h = harness(); assert.equal(h.run({ STAGE: 'candidate', PUBLISH: 'draft' }).status, 0); diff --git a/scripts/sdk-reference-release.mjs b/scripts/sdk-reference-release.mjs index 4306a4a1c..e0987351c 100644 --- a/scripts/sdk-reference-release.mjs +++ b/scripts/sdk-reference-release.mjs @@ -5,8 +5,11 @@ * * node scripts/sdk-reference-release.mjs [--ref ] [--stage released|candidate|preview] [--json] * - * Without --ref it picks the newest published SDK release: the commit of the - * newest `python-v*` tag. The result (printed as `key=value` lines, or JSON with + * Without --ref it picks the newest published SDK release: the SDK versions and + * publishes its Python and TypeScript packages independently, so it takes the newest + * `python-v*` tag and the newest `typescript-v*` tag and keeps whichever commit is + * later, so a TypeScript-only release is never missed and older pages are never + * proposed over newer ones. The result (printed as `key=value` lines, or JSON with * --json) carries the full commit SHA, the Python/TypeScript versions from the * SDK's release manifest at that commit, the backend release the contract was * synced from, and `branch`, the docs branch for this release: one branch (so one @@ -43,16 +46,46 @@ async function github(path) { return fetchJson(`https://api.github.com/repos/${SDK_REPO}/${path}`, { headers }); } -/** The newest python-v* tag's name (by semantic version, not by push order). */ -export function newestPythonTag(/** @type {{ref: string}[]} */ refs) { +/** + * The newest `vX.Y.Z` tag's name (by semantic version, not by push order), or + * null when that package has no release tag yet. + * @param {{ref: string}[]} refs @param {'python-' | 'typescript-'} prefix + */ +export function newestTag(refs, prefix) { + const pattern = new RegExp(`^${prefix}v(\\d+)\\.(\\d+)\\.(\\d+)$`); const versions = refs .map((ref) => ref.ref.replace('refs/tags/', '')) - .map((tag) => ({ tag, match: /^python-v(\d+)\.(\d+)\.(\d+)$/.exec(tag) })) + .map((tag) => ({ tag, match: pattern.exec(tag) })) .filter((entry) => entry.match) .map((entry) => ({ tag: entry.tag, version: entry.match.slice(1, 4).map(Number) })) .sort((a, b) => a.version[0] - b.version[0] || a.version[1] - b.version[1] || a.version[2] - b.version[2]); - if (!versions.length) throw new Error(`${SDK_REPO} has no python-v* release tag yet`); - return versions[versions.length - 1].tag; + return versions.length ? versions[versions.length - 1].tag : null; +} + +/** Kept for callers of the old name: the newest python-v* tag, or an error when none. */ +export function newestPythonTag(/** @type {{ref: string}[]} */ refs) { + const tag = newestTag(refs, 'python-'); + if (!tag) throw new Error(`${SDK_REPO} has no python-v* release tag yet`); + return tag; +} + +/** + * The newest published SDK commit across both package release streams: the newest + * Python tag and the newest TypeScript tag, resolved to commits, the later commit wins. + * @param {{ref: string}[]} refs + * @param {(ref: string) => Promise} resolveSha + * @param {(sha: string) => Promise} commitDate ISO 8601 committer date + * @returns {Promise<{ref: string, sha: string}>} + */ +export async function newestRelease(refs, resolveSha, commitDate) { + const tags = [newestTag(refs, 'python-'), newestTag(refs, 'typescript-')].filter((t) => t !== null); + if (!tags.length) throw new Error(`${SDK_REPO} has no python-v* or typescript-v* release tag yet`); + const candidates = await Promise.all(tags.map(async (tag) => { + const sha = await resolveSha(tag); + return { ref: tag, sha, date: Date.parse(await commitDate(sha)) }; + })); + candidates.sort((a, b) => b.date - a.date || a.ref.localeCompare(b.ref)); + return { ref: candidates[0].ref, sha: candidates[0].sha }; } /** @param {string} ref a tag, branch or commit; returns the full commit SHA. */ @@ -62,6 +95,12 @@ async function resolveSha(ref) { return commit.sha; } +/** @param {string} sha */ +async function commitDate(sha) { + const commit = await github(`commits/${sha}`); + return commit.commit.committer.date; +} + /** @param {string} path @param {string} sha */ async function fileAt(path, sha) { const file = await github(`contents/${path}?ref=${sha}`); @@ -96,23 +135,27 @@ export function decide({ stage, sha, python, typescript, installable }) { /** * @param {{ref?: string, stage?: string}} options - * @param {{resolveSha?: typeof resolveSha, fileAt?: typeof fileAt, tags?: () => Promise<{ref: string}[]>, onPyPI?: typeof onPyPI, onNpm?: typeof onNpm}} [io] + * @param {{resolveSha?: typeof resolveSha, fileAt?: typeof fileAt, commitDate?: typeof commitDate, tags?: () => Promise<{ref: string}[]>, onPyPI?: typeof onPyPI, onNpm?: typeof onNpm}} [io] */ export async function resolve(options, io = {}) { const get = { resolveSha: io.resolveSha ?? resolveSha, fileAt: io.fileAt ?? fileAt, - tags: io.tags ?? (() => github('git/matching-refs/tags/python-v')), + commitDate: io.commitDate ?? commitDate, + // Both package release streams; the SDK versions Python and TypeScript independently. + tags: io.tags ?? (async () => [...(await github('git/matching-refs/tags/python-v')), ...(await github('git/matching-refs/tags/typescript-v'))]), onPyPI: io.onPyPI ?? onPyPI, onNpm: io.onNpm ?? onNpm, }; let ref = options.ref?.trim() || ''; let stage = options.stage?.trim() || (ref ? 'preview' : 'released'); + let sha; if (!ref) { - ref = newestPythonTag(await get.tags()); + ({ ref, sha } = await newestRelease(await get.tags(), get.resolveSha, get.commitDate)); stage = options.stage?.trim() || 'released'; + } else { + sha = await get.resolveSha(ref); } - const sha = await get.resolveSha(ref); const manifest = JSON.parse(await get.fileAt('.release-please-manifest.json', sha)); const python = manifest['python']; const typescript = manifest['typescript/futureagi']; diff --git a/scripts/sdk-reference-release.test.mjs b/scripts/sdk-reference-release.test.mjs index 806774adb..f7eb1ee29 100644 --- a/scripts/sdk-reference-release.test.mjs +++ b/scripts/sdk-reference-release.test.mjs @@ -1,7 +1,7 @@ // @ts-check import assert from 'node:assert/strict'; import { test } from 'node:test'; -import { decide, newestPythonTag, resolve } from './sdk-reference-release.mjs'; +import { decide, newestPythonTag, newestRelease, newestTag, resolve } from './sdk-reference-release.mjs'; const SHA = 'd4631b0b5208e11ef55706b531609be427888704'; const files = { @@ -9,11 +9,12 @@ const files = { 'sdkgen/contracts/BACKEND_VERSION': 'v1.58.0\n', }; -/** @param {{pypi?: boolean, npm?: boolean, tags?: string[]}} world */ +/** @param {{pypi?: boolean, npm?: boolean, tags?: string[], shas?: Record, dates?: Record}} world */ function io(world = {}) { return { - resolveSha: async (/** @type {string} */ ref) => (ref === 'missing' ? Promise.reject(new Error('404')) : SHA), + resolveSha: async (/** @type {string} */ ref) => (ref === 'missing' ? Promise.reject(new Error('404')) : (world.shas?.[ref] ?? SHA)), fileAt: async (/** @type {string} */ path) => files[path], + commitDate: async (/** @type {string} */ sha) => world.dates?.[sha] ?? '2026-11-05T03:41:58Z', tags: async () => (world.tags ?? ['python-v0.6.9', 'python-v0.7.0', 'python-v0.6.14', 'typescript-v0.2.0']).map((t) => ({ ref: `refs/tags/${t}` })), onPyPI: async () => world.pypi ?? false, onNpm: async () => world.npm ?? false, @@ -26,6 +27,28 @@ test('newest python tag is chosen by version, not by string order', () => { assert.throws(() => newestPythonTag([{ ref: 'refs/tags/typescript-v0.2.0' }]), /no python-v\* release tag/); }); +test('the scheduled default follows both release streams: a newer TypeScript-only release wins', async () => { + const A = 'a'.repeat(40); // python-v0.7.0 and typescript-v0.2.0 shipped here + const B = 'b'.repeat(40); // typescript-v0.2.1 shipped later, from a newer SDK commit with newer pages + const world = { + tags: ['python-v0.7.0', 'typescript-v0.2.0', 'typescript-v0.2.1'], + shas: { 'python-v0.7.0': A, 'typescript-v0.2.0': A, 'typescript-v0.2.1': B }, + dates: { [A]: '2026-11-05T03:41:58Z', [B]: '2026-11-09T10:00:00Z' }, + }; + const chosen = await newestRelease(io(world).tags && (await io(world).tags()), io(world).resolveSha, io(world).commitDate); + assert.deepEqual(chosen, { ref: 'typescript-v0.2.1', sha: B }, 'the later commit, not the newest Python tag'); + const resolved = await resolve({}, io({ ...world, pypi: true, npm: true })); + assert.equal(resolved.sha, B); + assert.equal(resolved.ref, 'typescript-v0.2.1'); + // The other way round too: a newer Python-only release is not shadowed by TypeScript. + const flipped = { ...world, dates: { [A]: '2026-11-09T10:00:00Z', [B]: '2026-11-05T03:41:58Z' } }; + assert.equal((await resolve({}, io({ ...flipped, pypi: true, npm: true }))).sha, A); + // One stream only is still a release; no stream at all fails closed. + assert.equal(newestTag([{ ref: 'refs/tags/typescript-v0.2.0' }], 'python-'), null); + assert.equal((await newestRelease([{ ref: 'refs/tags/typescript-v0.2.0' }], async () => B, async () => '2026-11-09T10:00:00Z')).sha, B); + await assert.rejects(newestRelease([{ ref: 'refs/tags/v1' }], async () => A, async () => ''), /no python-v\* or typescript-v\* release tag/); +}); + test('one branch per SDK version pair; preview branches are keyed by commit', () => { const facts = { sha: SHA, python: '0.7.0', typescript: '0.2.0' }; assert.deepEqual(decide({ ...facts, stage: 'released', installable: true }), {