Node.jsTypeScript-nativeStable

Node.js / TypeScript SDK

TypeScript-native SDK with full async/await support. Runs on Node.js 18+ and works with Next.js server actions, Express, Fastify, and any Node runtime.

Installation

bash
npm install truenorth
# or
yarn add truenorth
# or
pnpm add truenorth

Initialize

typescript/lib/truenorth.ts
import { TrueNorthEngine } from "truenorth";
const engine = new TrueNorthEngine({
  provider: "openai",        // "openai" | "anthropic" | "gemini" | "ollama"
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY!,
  compliance: ["dpdp"],      // optional
});

Next.js Server Action

typescript/app/actions.ts
"use server";
import { engine } from "@/lib/truenorth";
export async function sendMessage(sessionId: string, message: string) {
  const session = await engine.getOrCreateSession({
    sessionId,
    yamlPath: "agents/medical_intake.yaml",
  });
  const response = await session.send(message);
  return {
    message:   response.message,
    extracted: response.extracted,
    complete:  response.complete,
    costUsd:   response.costUsd,
  };
}

Streaming (for chat UIs)

typescript/app/api/chat/route.ts
import { TrueNorthEngine } from "truenorth";
import { StreamingTextResponse } from "ai";
export async function POST(req: Request) {
  const { sessionId, message } = await req.json();
  const session = await engine.getOrCreateSession({ sessionId });
  const stream  = await session.stream(message);
  return new StreamingTextResponse(stream);
}

TypeScript Types

typescript
interface TurnResponse {
  message:        string;
  extracted:      Record<string, unknown>;
  pending:        string[];
  complete:       boolean;
  costUsd:        number;
  stage:          PipelineStage;
  confidence:     Record<string, number>;
  emotionValence: number;
}
interface SessionOutput {
  fields: Record<string, {
    value:      unknown;
    confidence: number;
    sourceTurn: number;
    sourceText: string;
  }>;
  totalCostUsd: number;
  turns:        number;
  durationMs:   number;
  language:     string;
}
type PipelineStage =
  | "language_detection"   | "emotion_detection"
  | "pii_detection"        | "conversation_planning"
  | "field_extraction"     | "conflict_detection"
  | "field_validation"     | "confidence_scoring"
  | "hallucination_firewall" | "output_generation"
  | "source_tracing"       | "cost_recording"
  | "mcp_tool_execution";