Olumi Assistants SDK (TypeScript)

Official TypeScript SDK for the Olumi Assistants Service. Build AI-assisted decision-making tools with full type safety.

Installation

npm install @olumi/assistants-sdk
# or
pnpm add @olumi/assistants-sdk
# or
yarn add @olumi/assistants-sdk

Quick Start

import { OlumiClient } from "@olumi/assistants-sdk";

const client = new OlumiClient({
  apiKey: process.env.OLUMI_API_KEY!,
});

// Draft a decision graph
const result = await client.draftGraph({
  brief: "Should we expand to international markets?",
});

console.log(result.graph);
// {
//   schema: "graph.v1",
//   nodes: [
//     { id: "q1", type: "question", label: "Expand internationally?" },
//     { id: "o1", type: "option", label: "Yes - expand now" },
//     { id: "o2", type: "option", label: "No - focus domestically" }
//   ],
//   edges: [
//     { from: "q1", to: "o1" },
//     { from: "q1", to: "o2" }
//   ]
// }

API Reference

Client Configuration

const client = new OlumiClient({
  apiKey: string;        // Required: Your Olumi API key
  baseUrl?: string;      // Optional: API base URL (default: production)
  timeout?: number;      // Optional: Request timeout in ms (default: 60000)
});

Methods

draftGraph(request)

Generate a decision graph from a brief description.

const response = await client.draftGraph({
  brief: "Should we launch feature X?",
  attachments: [  // Optional
    {
      filename: "data.csv",
      content_type: "text/csv",
      data: "base64-encoded-content",
    },
  ],
});

// response: DraftGraphResponse
// {
//   schema: "draft-graph.v1",
//   graph: Graph,
//   confidence: number,
//   issues?: string[]
// }

suggestOptions(request)

Generate additional options for a question node.

const response = await client.suggestOptions({
  graph: existingGraph,
  question_id: "q1",
});

// response: { schema: "suggest-options.v1", suggestions: string[] }

clarifyBrief(request)

Get clarifying questions for an ambiguous brief.

const response = await client.clarifyBrief({
  brief: "Improve our product",
  previous_answers: {  // Optional
    "q1": "User retention",
  },
});

// response: ClarifyBriefResponse
// {
//   questions: [{ id, question, reason }],
//   ready: boolean,
//   confidence: number
// }

critiqueGraph(request)

Get quality feedback on a decision graph.

const response = await client.critiqueGraph({
  graph: myGraph,
  brief: "Original brief",  // Optional
  focus_areas: ["structure", "completeness"],  // Optional
});

// response: CritiqueGraphResponse
// {
//   overall_quality: "excellent" | "good" | "fair" | "poor",
//   issues: [{ severity, category, message, node_ids? }]
// }

explainDiff(request)

Get natural language explanation of graph changes.

const response = await client.explainDiff({
  before: originalGraph,
  after: modifiedGraph,
});

// response: ExplainDiffResponse
// {
//   summary: string,
//   changes: [{ type, node_id?, before?, after? }]
// }

evidencePack(request)

Generate supporting evidence for a node.

const response = await client.evidencePack({
  graph: myGraph,
  node_id: "o1",
});

// response: EvidencePackResponse
// {
//   node_id: string,
//   evidence: [{ type: "pro" | "con" | "context", text, confidence }]
// }

healthCheck()

Check service health.

const response = await client.healthCheck();
// { status: "ok", version: "1.5.0" }

Error Handling

The SDK throws typed errors for different failure modes:

import { OlumiAPIError, OlumiNetworkError, OlumiConfigError } from "@olumi/assistants-sdk";

try {
  const result = await client.draftGraph({ brief: "..." });
} catch (error) {
  if (error instanceof OlumiAPIError) {
    // 4xx/5xx from server
    console.error(`API error: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
    console.error(`Code: ${error.code}`);
    console.error(`Request ID: ${error.requestId}`);
  } else if (error instanceof OlumiNetworkError) {
    // Network failure, timeout, etc.
    console.error(`Network error: ${error.message}`);
  } else if (error instanceof OlumiConfigError) {
    // Invalid SDK configuration
    console.error(`Config error: ${error.message}`);
  }
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  Graph,
  GraphNode,
  GraphEdge,
  DraftGraphRequest,
  DraftGraphResponse,
  // ... and more
} from "@olumi/assistants-sdk";

CEE v1 Helpers (Decision Engine)

The SDK includes a small, deterministic surface area for CEE v1 ("Controlled Evaluation Engine"):

• createCEEClient – typed client for CEE endpoints.
• buildDecisionStorySummary – metadata-only narrative summary.
• buildCeeJourneySummary – aggregates per-envelope health and completeness.
• buildCeeUiFlags – UI-ready booleans (high risk, truncation, disagreement, completeness).
• buildCeeDecisionReviewPayload – compact payload suitable for "decision review" APIs.
• isRetryableCEEError – classifies retryable CEE failures.

Recommended reading and examples:

• Docs/CEE-v1.md – CEE endpoints, error shapes, and judgement policy.
• Docs/CEE-recipes.md – canonical usage patterns (draft-only, draft+options, full journey).
• sdk/typescript/src/examples/ceeJourneyExample.ts – simple CEE journey via SDK.
• sdk/typescript/src/examples/ceeDecisionReviewExample.ts – Sandbox-style decision review payload example.
• sdk/typescript/src/examples/ceeCalibrationExample.ts – small calibration snapshot helper focusing on quality bands, truncation, and validation issues.
• Docs/CEE-sandbox-integration.md – how to integrate CEE into a Scenario/Sandbox-style Decision Review surface.

For contributors touching CEE helpers or contracts, also see Docs/CEE-maintainers-guide.md.

Examples

See examples/ directory for complete examples:

• Basic usage
• Error handling
• Streaming responses
• Multi-step workflows

License

MIT