@gigaflow/client

The GigaFlow control plane: run evaluations, read datasets, write feedback.

npm install @gigaflow/client

This is the offline half of GigaFlow. @gigaflow/sdk is for tracing what your agent does in production; this package is for scoring it against data you keep. They are separate installs because most people need only one, and the two move on different clocks.

Eval()

import { Eval } from '@gigaflow/client'

const summary = await Eval({
  apiUrl: 'https://api.gigaflow.io',
  token: process.env.GIGAFLOW_TOKEN,
  project: projectId, // UUID
  experiment: 'summariser-v3',
  data: [{ input: 'the meeting notes…', expected: 'a one-line summary' }],
  task: async (input) => summarise(input),
  scores: [({ output }) => (/\d{4}-\d{2}-\d{2}/.test(String(output)) ? 1 : 0)],
})

console.log(summary.scores) // { score_0: 1 }

An experiment runs task over every row, applies each scorer, and reports the results to GigaFlow as a comparable run. Rows are independent: a scorer that throws fails that row, recorded as an error on the case, rather than the run.

data also accepts { dataset_id, version } to run against rows curated in the UI — pinning version makes the run reproducible against an immutable snapshot.

Full guide, including the options reference: docs/evaluations.md.

Durable subject events

initSubjectEvents() delivers immutable external outcomes with bounded retries, strict response validation, and a required final-failure callback. Subjects are canonical qualified identities such as github:GigaFlowAI/gigarepo#1102; unqualified legacy identifiers are rejected. The bundled githubActionsAdapter.pullRequestClosed() builds the versioned event envelope, including the stable { kind, instance } source identity used for installation, consent, and retention policy.

import { githubActionsAdapter, initSubjectEvents } from '@gigaflow/client'

const outcomes = initSubjectEvents({
  apiUrl: 'https://api.gigaflow.io',
  token: process.env.GIGAFLOW_TOKEN!,
  onFinalFailure: ({ error, request }) => persistForOperatorReplay(error, request),
})

await outcomes.deliver([
  githubActionsAdapter.pullRequestClosed({
    repository_id: repositoryId,
    workflow_run_id: runId,
    repository: 'GigaFlowAI/gigarepo',
    pull_request_number: 1102,
    closed_at: closedAt,
    merged,
    merge_sha: mergeSha,
    compare: completeImmutableCompare,
  }),
])

Versioning

0.x, and the minor is the breaking position — 0.2.0 may break 0.1.x; a patch never will. This is standard 0.x semver and it is widely misread, so it is worth saying plainly: ^0.1.0 does not protect you across a minor bump. Pin ~0.1.0 if you need it to.

The emitted wire format is versioned separately from this package, under gigaflow.schema.version. Every changelog entry says whether it moved — that, not the TypeScript surface, is your real upgrade risk.

Licence

Apache-2.0.