SDK Reference

import os
from seyn import SeynClient

seyn = SeynClient(api_key=os.environ["SEYN_API_KEY"])

result = seyn.knowledge.query(q="When does a loan need senior approval?", top_k=5)
for hit in result.results:
    print(f"[{hit.score:.2f}] {hit.description}")

trail = seyn.rules.provenance(result.results[0].rule_id)
print(f"{len(trail.source_events)} events, {len(trail.raw_records)} raw records")

import { SeynClient } from "@seyn/sdk";

const client = new SeynClient({
  apiKey: process.env.SEYN_API_KEY!,
  // baseUrl: "https://api-dev.seynlabs.com",  // optional, defaults to api.seynlabs.com
});

const result = await client.knowledge.query({
  q: "When does a loan need senior approval?",
  topK: 5,
  strategy: "hybrid",          // optional: "auto" | "structured" | "hybrid" | "graph"
  libraryId: "uuid-here",       // optional: limit to one library
  includeExplain: true,         // optional: include the retrieval explain blob
});

// result.results is V1KnowledgeQueryHit[]
for (const hit of result.results) {
  console.log(`[${hit.score.toFixed(2)}] ${hit.description}`);
}

{
  results: Array<{
    ruleId: string;
    description: string;
    processId: string | null;
    processName: string | null;
    step: string | null;
    confidence: number;
    score: number;
  }>;
  explain?: V1RetrievalExplain;  // present only if includeExplain was true
}

const memory = await client.knowledge.memory({
  text: "Deals over $50M always need board sign-off, not just the CEO.",
  // libraryId: "uuid-here",   // optional: defaults to the active library
});

// poll until applied
const status = await client.knowledge.memoryStatus(memory.memoryId);
if (status.status === "applied") {
  console.log(status.summary);
  console.log(`${status.assertionsCreated} created, ${status.assertionsSuperseded} superseded`);
}

const rules = await client.rules.list({
  reviewStatus: "confirmed",   // "inferred" | "confirmed" | "modified" | "rejected"
  libraryId: "uuid-here",
  search: "approval",
  limit: 50,
  offset: 0,
});

const rule = await client.rules.get("7f3cb37f-7d67-43f1-a3eb-a95ffdafb6b9");
console.log(rule.condition);   // structured logic tree
console.log(rule.evidence);    // supporting evidence

const trail = await client.rules.provenance(rule.id);

console.log(trail.rule.description);
console.log(`Produced by ${trail.inferenceLog?.model}`);
console.log(`From ${trail.sourceEvents.length} events,`);
console.log(`across ${trail.rawRecords.length} raw records`);
console.log(`ingested via ${trail.rawRecords[0]?.connectorType}`);

const libraries = await client.libraries.list({
  status: "active",   // "draft" | "active" | "archived"
  limit: 20,
});

const lib = await client.libraries.get("uuid-here");
console.log(`Library v${lib.version}, status=${lib.status}`);

const rules = await client.libraries.rules("library-uuid", {
  reviewStatus: "confirmed",
  limit: 100,
});

const m = await client.patterns.metrics();

console.log(`${m.totalDeals} total deals, ${m.totalDeadDeals} dead`);
console.log("Median days in each stage:");
for (const row of m.stageVelocity) {
  console.log(`  ${row.stage}: ${row.medianDays}d (p90 ${row.p90Days}d)`);
}

const source = await client.sources.create({
  name: "Internal CRM",
  entityTypes: ["deal", "account", "activity"],
});

const batch = await client.ingest({
  sourceId: source.id,
  records: [
    {
      recordId: "deal-4471",
      entityType: "deal",
      sourceUpdatedAt: "2026-06-10T14:03:00Z",
      payload: {
        name: "Acme Corp renewal",
        stage: "negotiation",
        amount: 42000,
        owner: "jane.smith@acme.com",
        movedToStageBy: "jane.smith@acme.com",
      },
    },
  ],
});

console.log(`${batch.accepted} accepted, ${batch.deduplicated} deduped`);

const status = await client.ingest.status(batch.batchId);
if (status.status === "done") {
  console.log(`${status.recordsCreated} records, ${status.eventsCreated} events`);
}

import { SeynClient, SeynError } from "@seyn/sdk";

try {
  await client.rules.get("missing-id");
} catch (err) {
  if (err instanceof SeynError) {
    if (err.code === "NOT_FOUND") {
      return null;
    }
    if (err.code === "RATE_LIMITED") {
      // Back off for 60s before retrying. Replace with your own retry/backoff strategy.
      await new Promise((resolve) => setTimeout(resolve, 60_000));
      // retry...
    }
    if (err.code === "KEY_REVOKED") {
      // Wire this up to PagerDuty / Slack / whatever your team uses.
      console.error("Seyn key was revoked: rotate ASAP");
    }
    console.error(err.code, err.statusCode, err.message);
  }
  throw err;
}

class SeynError extends Error {
  code: V1ErrorCode | "UNKNOWN_ERROR";
  statusCode: number;
  requestId: string | undefined;  // include in support tickets
  message: string;
}

const ac = new AbortController();
setTimeout(() => ac.abort(), 5_000);

try {
  const rules = await client.rules.list({ signal: ac.signal });
} catch (err) {
  if (err.name === "AbortError") {
    console.log("query took too long, gave up");
  }
}

await client.rules.list({ signal: AbortSignal.timeout(5_000) });