This page catalogs the TypeScript types and constants the SDK exports — the shapes of its configuration, job progress events, submission parameters, and the JOB_TYPES registry of supported tools. Reach for it when you want compile-time safety on the values you pass to and receive from the Client and Jobs methods, or when you need the canonical list of valid tool names and job statuses. It also documents the Harness session types used by the Harness Sessions API.

SDK Types Reference

Planned specification. @ivybiosciences/sdk is not released, and there is no package to install. This page describes the SDK's planned interface. To call the platform today, use the REST API, the ivybloom CLI, or the MCP server.

Core TypeScript types exported from @ivybiosciences/sdk. These types define the SDK's configuration, events, and domain models.

import type {
  IvyClientConfig,
  JobStatus,
  JobProgress,
  JobProgressCallback,
  SubmitJobParams,
  SubmitAndWaitOptions,
  WebSocketOptions,
  JobType,
} from "@ivybiosciences/sdk"

`JobStatus`

All possible states for a computational job in the IvyAI system.

type JobStatus =
  | "PENDING"
  | "STARTED"
  | "PROCESSING"
  | "PROGRESS"
  | "COMPLETED"
  | "FAILURE"
  | "CANCELLED"
  | "IMPORTED"

Lifecycle Diagram

Job status lifecycle.

Values

Status	Description
`PENDING`	Job accepted and queued for execution
`STARTED`	Modal container provisioned, initializing
`PROCESSING`	Main computation running
`PROGRESS`	Intermediate update (may include phase info)
`COMPLETED`	Finished successfully; results available
`FAILURE`	Fatal error; see `JobProgress.error`
`CANCELLED`	Cancelled by user before completion
`IMPORTED`	Migrated from another system (guest → authenticated)

`TERMINAL_STATUSES`

Set of JobStatus values that indicate a job has reached a final state.

const TERMINAL_STATUSES: ReadonlySet<JobStatus>
// Contains: "COMPLETED", "FAILURE", "CANCELLED"

Once a job is in a terminal status, it will never change status again.

Example

import { TERMINAL_STATUSES } from "@ivybiosciences/sdk"

if (TERMINAL_STATUSES.has(job.status)) {
  console.log("Job is done")
}

`IvyClientConfig`

Configuration for creating an IvyClient instance. Exactly one of apiKey or getToken must be provided.

interface IvyClientConfig {
  baseUrl?: string
  apiKey?: string
  getToken?: () => Promise<string | null>
  timeout?: number
  retries?: number
  onError?: (error: Error) => void
}

Fields

Field	Type	Default	Description
`baseUrl`	`string`	Production endpoint	API base URL including `/api/v1` prefix
`apiKey`	`string`	—	API key with `ivy_` prefix. Mutually exclusive with `getToken`
`getToken`	`() => Promise<string \| null>`	—	Async JWT provider (e.g., Clerk). Mutually exclusive with `apiKey`
`timeout`	`number`	`30000`	HTTP request timeout in milliseconds
`retries`	`number`	`3`	Max retries for transient failures (429, 5xx)
`onError`	`(error: Error) => void`	—	Global callback for unhandled SDK errors

Examples

// Server-side with API key
const config: IvyClientConfig = {
  apiKey: "ivy_your_key_here",
  timeout: 60_000,
}

// Browser with Clerk JWT
const config: IvyClientConfig = {
  getToken: () => clerk.session!.getToken({ template: "ivy_api" }),
  baseUrl: "https://your-domain.com/api/v1",
}

`JobProgress`

Real-time progress snapshot of a computational job. Delivered via WebSocket subscription or HTTP polling.

interface JobProgress {
  jobId: string
  status: JobStatus
  progress?: number
  phase?: string
  result?: Record<string, unknown>
  error?: string
  presignedUrl?: string
  updatedAt?: string
}

Fields

Field	Type	Description
`jobId`	`string`	Unique job identifier (format: `job_{uuid4}`)
`status`	`JobStatus`	Current lifecycle state
`progress`	`number?`	Overall completion percentage (0–100)
`phase`	`string?`	Current computational phase name
`result`	`Record<string, unknown>?`	Structured result data (only when COMPLETED)
`error`	`string?`	Error description (only when FAILURE)
`presignedUrl`	`string?`	Time-limited S3 download URL for artifacts
`updatedAt`	`string?`	ISO 8601 timestamp of last status change

Standard Phases

Phase	Typical Progress	Description
`initialization`	~5%	Input validation
`data_preprocessing`	~15%	Data loading and prep
`model_loading`	~10%	ML model initialization
`main_computation`	~50%	Core processing
`post_processing`	~15%	Result analysis
`result_generation`	~5%	Format and store

Examples

// During computation
{
  jobId: "job_abc123",
  status: "PROCESSING",
  progress: 45,
  phase: "main_computation"
}

// Completed result
{
  jobId: "job_abc123",
  status: "COMPLETED",
  progress: 100,
  result: { plddt_mean: 0.87, num_residues: 342 },
  presignedUrl: "https://<bucket>.s3.<region>.amazonaws.com/.../predicted_structure.pdb"
}

`JobProgressCallback`

Callback function invoked with progress updates during job execution.

type JobProgressCallback = (progress: JobProgress) => void

Used by SubmitAndWaitOptions.onProgress and the useIvyJob hook.

`SubmitJobParams`

Parameters for submitting a new computational job.

interface SubmitJobParams {
  toolName: string
  parameters: Record<string, unknown>
  projectId?: string
  jobTitle?: string
  orgId?: string
  analysisLevel?: "basic" | "standard" | "comprehensive"
}

Fields

Field	Type	Required	Description
`toolName`	`string`	Yes	Computational tool to run (see `JOB_TYPES`)
`parameters`	`Record<string, unknown>`	Yes	Tool-specific input parameters
`projectId`	`string`	No	Project for billing/access control
`jobTitle`	`string`	No	Human-readable title for dashboard
`orgId`	`string`	No	Organization ID for team-scoped jobs
`analysisLevel`	`"basic" \| "standard" \| "comprehensive"`	No	Analysis depth (default: `"standard"`)

Analysis Levels

Level	Description	Data Fields
`basic`	Fast results, minimal metrics	Standard output only
`standard`	Balanced analysis (default)	Key quality metrics
`comprehensive`	Full analytical suite	5-10x more fields

Examples

// ESMFold protein structure prediction
const params: SubmitJobParams = {
  toolName: "esmfold",
  parameters: { protein_sequence: "MKFLILLFNILCLFPVLAADNH" },
  analysisLevel: "comprehensive",
}

// DiffDock molecular docking
const params: SubmitJobParams = {
  toolName: "diffdock",
  parameters: {
    protein_pdb: "...",
    ligand_smiles: "CC(=O)Oc1ccccc1C(=O)O",
    num_poses: 10,
  },
  projectId: "proj_abc123",
  jobTitle: "Aspirin docking study",
}

`SubmitAndWaitOptions`

Options for the submitAndWait() convenience method. Controls how the SDK monitors job progress until completion.

interface SubmitAndWaitOptions {
  onProgress?: JobProgressCallback
  pollInterval?: number
  timeout?: number
  useWebSocket?: boolean
}

Fields

Field	Type	Default	Description
`onProgress`	`JobProgressCallback`	—	Called on each status/progress change
`pollInterval`	`number`	`3000`	Polling interval in ms (fallback mode)
`timeout`	`number`	`600000`	Max wait time in ms (throws `IvyTimeoutError`)
`useWebSocket`	`boolean`	`true`	Use WebSocket for real-time updates

`WebSocketOptions`

Configuration for WebSocket connection behavior. Controls reconnection strategy and lifecycle callbacks.

interface WebSocketOptions {
  autoReconnect?: boolean
  maxReconnectAttempts?: number
  reconnectInterval?: number
  onReconnect?: (attempt: number) => void
  onClose?: (code: number, reason: string) => void
}

Fields

Field	Type	Default	Description
`autoReconnect`	`boolean`	`true`	Reconnect on unexpected close (non-1000 code)
`maxReconnectAttempts`	`number`	`5`	Max consecutive reconnection attempts
`reconnectInterval`	`number`	`1000`	Base delay in ms (doubles each attempt)
`onReconnect`	`(attempt: number) => void`	—	Called on each reconnection attempt
`onClose`	`(code: number, reason: string) => void`	—	Called when connection closes

Reconnection Backoff

Attempt 1: wait reconnectInterval ms         (1s)
Attempt 2: wait reconnectInterval * 2 ms     (2s)
Attempt 3: wait reconnectInterval * 4 ms     (4s)
Attempt 4: wait reconnectInterval * 8 ms     (8s)
Attempt 5: wait reconnectInterval * 16 ms    (16s)
— Give up after maxReconnectAttempts —

`JobType`

Union type of all valid tool names. Derived from the JOB_TYPES constant.

type JobType = keyof typeof JOB_TYPES
// "esmfold" | "esm3_generate" | "diffdock" | "admet_ai" | ...

Example

import type { JobType } from "@ivybiosciences/sdk"

const tool: JobType = "esmfold" // OK
const bad: JobType = "invalid"  // TypeScript error

Constants

Exported constants from the main entry point:

import { DEFAULT_BASE_URL, JOB_TYPES } from "@ivybiosciences/sdk"

Constant	Value	Description
`DEFAULT_BASE_URL`	`"https://www.ivybiosciences.com/api/v1"`	Planned default: the web app's API on our own domain
`JOB_TYPES`	`{ esmfold: "...", ... }`	Complete tool registry (see below)

Internal Defaults

These values are used internally by the SDK and configured via IvyClientConfig or SubmitAndWaitOptions. They are not exported but documented here for reference:

Default	Value	Configured via
HTTP timeout	`30000` (30s)	`IvyClientConfig.timeout`
Retry attempts	`3`	`IvyClientConfig.retries`
Poll interval	`3000` (3s)	`SubmitAndWaitOptions.pollInterval`
Wait timeout	`600000` (10min)	`SubmitAndWaitOptions.timeout`
WS ping interval	`25000` (25s)	Not configurable

`JOB_TYPES` Registry

Complete registry of supported computational tools.

Structure Prediction

Key	Description
`esmfold`	Protein structure prediction (GPU)
`esm3_generate`	ESM3 protein generation
`esm3_inverse_fold`	ESM3 inverse folding
`esm3_embeddings`	ESM3 protein embeddings

Molecular Docking & Design

Key	Description
`diffdock`	Protein-ligand docking (GPU)
`reinvent`	De novo molecule generation
`fragment_growing`	Fragment-based drug design. Retired, no replacement
`fragment_library`	Fragment library management. Retired, no replacement

Property Prediction

Key	Description
`admet_ai`	ADMET property prediction
`admetlab3`	ADMETLab3 comprehensive profiling. Retired, use `admet_ai`
`graphsol`	Aqueous solubility prediction
`deepsol`	Deep learning solubility. Not currently callable, use `graphsol`
`protox3`	Protein toxicity prediction. Retired, use `admet_ai` for the overlapping endpoints
`deeppurpose`	Drug-target interaction

Database Screening

Key	Description
`rdkit_full`	RDKit SMILES validation & properties
`zinc`	ZINC database screening
`pubchem`	PubChem compound queries

Sequence & Structure

Key	Description
`blast`	Sequence homology search
`biotite_fetch`	UniProt/PDB structure fetching
`aizynthfinder`	Retrosynthetic route planning

Literature & NLP

Key	Description
`biobert_pubmed`	Scientific literature mining

Example

import { JOB_TYPES } from "@ivybiosciences/sdk"

if ("esmfold" in JOB_TYPES) {
  console.log(JOB_TYPES.esmfold) // "Protein structure prediction (GPU)"
}

Harness Types

Types used by the Harness Sessions API. Exported from @pleach/core/types.

`SessionState`

The full state of a harness session.

interface SessionState {
  id: string
  userId: string
  title: string
  messages: SessionMessage[]
  toolCalls: ToolCallRecord[]
  artifacts: ArtifactRecord[]
  versionVector: VersionVector
  status: "active" | "archived"
  authPreset: "lenient" | "standard" | "light"
  createdAt: string
  updatedAt: string
}

`StreamEvent`

Events emitted during harness session execution via SSE. See Message Execution for the full reference.

interface StreamEvent {
  type: StreamEventType
  data: Record<string, unknown>
}

type StreamEventType =
  | "message.start" | "message.delta" | "message.complete" | "message.citations" | "message.file"
  | "tool_call.start" | "tool_call.delta" | "tool_call.complete" | "tool_call.error" | "tool_call.pending"
  | "job.submitted" | "job.progress" | "job.completed" | "job.failed" | "job.cancelled"
  | "artifact.created" | "artifact.ready"
  | "interrupt.requested" | "interrupt.resolved"
  | "state.checkpoint" | "state.updated" | "state.rollback"
  | "sync.completed" | "sync.conflict"
  | "error.runtime" | "error.validation" | "error.tool"

`VersionVector`

Used for multi-client synchronization. See Sync Protocol.

interface VersionVector {
  [clientId: string]: HybridTimestamp
}

interface HybridTimestamp {
  wallTime: number
  logical: number
  nodeId: string
}

`SyncMode`

Conflict resolution mode for the sync endpoint.

type SyncMode = "merge" | "force_local" | "force_remote"

`CheckpointSource`

What triggered a checkpoint.

type CheckpointSource = "message" | "tool_execution" | "job_complete" | "sync" | "manual"

Types & Constants