@fdekit/core

Purpose

@fdekit/core is the authoring contract for FDEKit deployments. It contains the TypeScript helpers and types used in fde.config.ts: deployments, agents, tools, connectors, providers, governance, evals, harnesses, recipes, workflow metadata, rollout metadata, schema helpers, policy helpers, provider-planner contracts, and the review findings contract (spec).

Use core when you are describing what a deployment is. Do not put runtime file I/O, artifact persistence, CLI behavior, or provider HTTP calls here.

Who should use this package

• Deployment authors writing fde.config.ts.
• Connector and provider authors who need shared FDEKit contracts.
• Contributors changing public config shapes, policy helpers, eval assertions, or tool schema helpers.

Choose @fdekit/runtime instead when you need to load configs, run agents, write artifacts, or inspect traces. Choose @fdekit/cli when you only need the command-line workflow.

5-minute quick example

import {
  defineAgent,
  defineDeployment,
  defineEval,
  expectedApprovalOutcome,
  expectedFinalAnswer,
  expectedToolCall,
  providerFromEnv,
} from '@fdekit/core';

const provider = providerFromEnv();

export default defineDeployment({
  name: 'support-triage',
  environment: 'local',
  providers: {
    [provider.name]: provider,
  },
  agents: {
    supportTriage: defineAgent({
      provider: provider.name,
      instructions: './agents/support-triage.md',
    }),
  },
  evals: [
    defineEval({
      name: 'answers-support-request',
      agent: 'supportTriage',
      dataset: './evals/support-triage.json',
      assertions: [
        expectedToolCall('ticket.get'),
        expectedFinalAnswer(/support|ticket/i),
      ],
    }),
  ],
});

Approval feedback assertions

expectedApprovalOutcome() consumes the expected.toolName and expected.shouldProceed fields written by fdekit feedback export. It passes when an approved tool is observed, or when a rejected tool is absent:

defineEval({
  name: 'approval-feedback',
  agent: 'supportTriage',
  dataset: './artifacts/feedback/eval-cases.json',
  assertions: [expectedApprovalOutcome()],
})

Rubric judges

judgeRubric is a bring-your-own-judge assertion. FDEKit does not automatically call the deployment provider or ship a built-in LLM judge. Pass a judge function that returns an EvalAssertionResult; fdekit validate reports an error when the function is missing.

import { judgeRubric } from '@fdekit/core';

const answerQuality = judgeRubric({
  rubric: 'The answer is accurate, polite, and complete.',
  async judge(context, rubric) {
    // Call the model or deterministic judge selected for your eval environment.
    const passed = Boolean(context.finalAnswer?.includes('please'));

    return {
      passed,
      score: passed ? 1 : 0,
      message: passed ? `Passed: ${rubric}` : `Failed: ${rubric}`,
    };
  },
});

S3 artifact storage

S3 storage uses an injected client so FDEKit does not require the AWS SDK. The client field is required and must implement putObject, getObject, and listObjectsV2. @fdekit/core exports S3ArtifactClient and the related input/output types for custom AWS, MinIO, LocalStack, or enterprise adapters.

import { defineDeployment, type S3ArtifactClient } from '@fdekit/core';
import {
  GetObjectCommand,
  ListObjectsV2Command,
  PutObjectCommand,
  S3Client,
} from '@aws-sdk/client-s3';

const s3 = new S3Client({ region: process.env.AWS_REGION });

const artifactsClient: S3ArtifactClient = {
  putObject: (input) => s3.send(new PutObjectCommand(input)),
  getObject: (input) => s3.send(new GetObjectCommand(input)),
  listObjectsV2: (input) => s3.send(new ListObjectsV2Command(input)),
};

export default defineDeployment({
  // providers and agents...
  artifacts: {
    kind: 's3',
    bucket: 'fdekit-artifacts',
    client: artifactsClient,
  },
});

Public API surface

Import from the package root:

import { defineDeployment, defineTool, objectArgs } from '@fdekit/core';

The API reference documents all public root exports, including defineDeployment, defineAgent, providerFromEnv, defineConnector, defineTool, defineEval, objectArgs, policy helpers, eval assertions, and public config/provider/tool types: Core API Reference.

Stability/backward-compat notes

@fdekit/core is public but pre-1.0. Package-root exports are the compatibility boundary. Subpath imports from src, dist, helpers, or interfaces are internal and may change without a public migration note.

Breaking changes to core types or helper behavior should update the API reference and relevant cookbooks because deployment configs depend on this package.

See also

• Runtime execution: @fdekit/runtime
• CLI workflow: fdekit
• Static dashboard renderer: @fdekit/console
• Provider packages: mock, OpenAI, Anthropic, Google, Ollama
• Connector packages: customer API, codebase, GitHub, Slack, Jira, Linear, Postgres, k6, HubSpot, Salesforce
• Environment packages: Docker, Floci