@uks/sdk

TypeScript SDK for building and validating Universal Knowledge & Action Schema (UKS) v3.0 packets.

npm install @uks/sdk

Usage

Build a packet

import { UKSPacketBuilder } from '@uks/sdk';

// new UKSPacketBuilder(topic, packetId) — topic first, then the packet id.
// topic may be a string (wrapped into { title }) or a full Topic object.
const packet = new UKSPacketBuilder('My Research Topic', 'uks-my-topic-v1')
  .addSource({
    id: 'src_001',
    title: 'Key study on the topic',
    source_type: 'research_paper',
    credibility_score: 9,
    evidence_grade: 'high',
    clinical_status: 'validated',
    doi: '10.1000/example',
    summary: 'This study found...',
    key_findings: ['Finding one', 'Finding two'],
    tags: ['keyword1', 'keyword2'],
    license_label: 'CC BY 4.0',
    rights_url: 'https://creativecommons.org/licenses/by/4.0/',
  })
  .build();

console.log(JSON.stringify(packet, null, 2));

Validate a packet

import { validate } from '@uks/sdk';

const result = validate(packet);
if (!result.valid) {
  console.error(result.errors);
}
console.log(`Level: ${result.inferredLevel}, match: ${result.levelMatch}`);

Build and validate together

const packet = builder.buildAndValidate(); // throws on schema error

Add scrape targets (L2)

builder.addScrapeTarget({
  id: 'st_pubmed',
  api_id: 'pubmed',
  url_template: 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term={query}&retmode=json',
  http_method: 'GET',
  auth_type: 'none',
  source_type: 'peer_reviewed',
  source_domain: 'bibliographic',
  rate_limit: { requests_per_minute: 10 },
});

Import from BibTeX / RIS

import { importBibTeX, importRIS } from '@uks/sdk';

const packet = importBibTeX(bibtexString);
const packet2 = importRIS(risString);

Scaffold from OpenAPI

import { scaffoldFromOpenAPI } from '@uks/sdk';
import { readFileSync } from 'fs';

const spec = JSON.parse(readFileSync('openapi.json', 'utf8'));
const packet = scaffoldFromOpenAPI(spec, { topic: 'PubMed API' });

Export formats

import { exportToJSONLD, exportToFHIR } from '@uks/sdk';

const jsonld = exportToJSONLD(packet);   // schema.org Dataset
const fhir   = exportToFHIR(packet);    // FHIR R4 Bundle of Citations

API Reference

| Export | Description | |--------|-------------| | UKSPacketBuilder | Fluent builder for UKS packets | | validate(packet) | Returns { valid, errors, inferredLevel, levelMatch } | | importBibTeX(content) | BibTeX string → UKS L1 packet | | importRIS(content) | RIS string → UKS L1 packet | | scaffoldFromOpenAPI(spec) | OpenAPI 3.x → UKS L2 scaffold | | exportToJSONLD(packet) | UKS → schema.org JSON-LD | | exportToFHIR(packet) | UKS → FHIR R4 Citation Bundle |

Full type definitions in dist/index.d.ts.

Build

The SDK is written in TypeScript and must be compiled before use:

npm install
npm run build   # outputs to dist/

Links

• Specification
• CLI (uks-cli)
• Python SDK (uks-sdk)
• MCP Server (@uks/mcp-server)
• GitHub

License

MIT