◎OpenBio

For Developers

SDK Preview

The @openbio/sdk is a typed TypeScript client for the full OpenBio API. Install once, access ingest, query, and agent context from a single interface.

bash
npm install @openbio/sdk

Ingest

Push data from any source: FHIR bundles, CSV files, HL7v2 messages. Every ingested assertion is stamped with provenance and assigned a trust layer automatically.

Parameters

ParameterTypeDescription
sourceSystemIdstringRegistered source system identifier
bundle / file / messageobject | Buffer | stringThe payload to ingest (format-specific)
const client = new OpenBio({ apiKey: process.env.OPENBIO_API_KEY });

// Ingest a FHIR R4 Bundle
const result = await client.ingest.fhir({
  sourceSystemId: 'epic-mount-sinai',
  bundle: fhirBundle, // FHIR R4 Bundle object
});

// Returns: { assertionsCreated: number, subjectsUpdated: number, ingestionId: string }
console.log(`Created ${result.assertionsCreated} assertions`);

Query

Retrieve evidence assertions with trust filtering, type constraints, and temporal ranges. Every response includes full provenance metadata.

Return type

typescript
interface EvidenceAssertion {
  id: string;
  subjectId: string;
  type: string;
  value: number | string;
  unit?: string;
  trustLayer: 'source_fact' | 'normalized_fact' | 'extracted_annotation' | 'derived_feature' | 'model_output' | 'hypothesis';
  confidence: number;
  temporalContext: { observedAt: string; certainty: string };
  provenance: {
    source: string;
    protocol: string;
    collectedAt: string;
    receivedAt: string;
  };
}
// Fetch all evidence for a subject with trust filtering
const evidence = await client.evidence.bySubject({
  subjectId: 'james-58',
  trustLayer: ['source_fact', 'normalized_fact'],
  type: 'lab_result',
  limit: 50,
});

// Returns: EvidenceAssertion[]
for (const assertion of evidence) {
  console.log(assertion.value, assertion.unit, assertion.trustLayer);
  console.log(assertion.provenance.source, assertion.provenance.collectedAt);
}

AI Agents

Retrieve structured evidence context formatted for LLM consumption. Typed assertions with trust scores and provenance — exactly what an agent needs to reason about biological evidence.

typescript
// Get structured evidence context for an LLM agent
const context = await client.agents.evidenceContext({
  subjectId: 'james-58',
  format: 'structured',
  maxAssertions: 50,
  trustLayers: ['source_fact', 'normalized_fact', 'derived_feature'],
});

// Returns typed JSON payload ready for LLM tool use:
// {
//   subject: { id, name, age, subjectType }
//   assertions: EvidenceAssertion[]
//   summary: { totalCount, byType, byTrustLayer }
//   provenanceSummary: { sources: string[], protocols: string[] }
// }

// Plug directly into a tool call:
const response = await anthropic.messages.create({
  model: 'claude-opus-4-6',
  tools: [getSubjectEvidenceTool],
  messages: [{ role: 'user', content: userQuery }],
});

Error handling

The SDK throws typed OpenBioError instances. Check the code discriminant to handle specific failure modes.

typescript
import { OpenBio, OpenBioError } from '@openbio/sdk';

const client = new OpenBio({ apiKey: process.env.OPENBIO_API_KEY });

try {
  const evidence = await client.evidence.bySubject({ subjectId: 'james-58' });
} catch (err) {
  if (err instanceof OpenBioError) {
    switch (err.code) {
      case 'NOT_FOUND':
        // Subject does not exist
        break;
      case 'UNAUTHORIZED':
        // API key missing or invalid
        break;
      case 'RATE_LIMITED':
        // Slow down — retry after err.retryAfter ms
        break;
      case 'VALIDATION_ERROR':
        // Bad request parameters — err.fields has per-field details
        break;
      default:
        // Unexpected error — err.message has details
        throw err;
    }
  }
  throw err;
}

SDK Preview

@openbio/sdk is in preview. The package will be published to npm at launch. In the meantime, try every call live in the API Playground