@fidelius-ai/sdk

Official TypeScript SDK for the Fidelius AI API.

Installation

npm install @fidelius-ai/sdk
# or
yarn add @fidelius-ai/sdk
# or
pnpm add @fidelius-ai/sdk

Quick Start

import { Fidelius } from "@fidelius-ai/sdk";

const client = new Fidelius({
  apiKey: process.env.FIDELIUS_API_KEY,
});

// Run an agent
const response = await client.agents.run({
  message: "What's the weather like today?",
  enable_web_search: true,
});

console.log(response.message);

Configuration

const client = new Fidelius({
  apiKey: "your-api-key",      // Required (or set FIDELIUS_API_KEY env var)
  baseUrl: "https://api.fidelius.ai/v1",  // Optional
  timeout: 60000,              // Request timeout in ms (default: 60000)
  maxRetries: 2,               // Retry count for transient errors (default: 2)
});

Resources

Agents

// Synchronous execution
const response = await client.agents.run({
  message: "Hello!",
  session_id: "optional-session-id",
  enable_memory: true,
  enable_web_search: true,
  enable_code_execution: false,
  temperature: 0.7,
  max_tokens: 4096,
});

// Streaming execution
for await (const event of client.agents.runStreaming({
  message: "Explain quantum computing",
})) {
  switch (event.type) {
    case "text":
      process.stdout.write(event.content);
      break;
    case "message_complete":
      console.log(`\nTokens: ${event.usage.total_tokens}`);
      break;
  }
}

// Stream with close control
const stream = client.agents.runStream({ message: "..." });
for await (const event of stream) {
  // Process events...
  if (shouldStop) {
    await stream.close();
    break;
  }
}

Memories

// Ingest memories from a conversation
const ingestResult = await client.memories.ingest({
  source: {
    type: "conversation",
    messages: [
      { role: "user", content: "I love hiking." },
      { role: "assistant", content: "That's great!" },
    ],
  },
  extraction_config: {
    confidence_threshold: 0.6,
  },
});

// Check ingest status
const status = await client.memories.getIngestStatus(ingestResult.id);

// Recall memories (synchronous)
const recalled = await client.memories.recall({
  query: "What are my hobbies?",
  token_budget: 1000,
  networks: ["world", "experience"],
  options: { rerank: true },
});

// Recall memories (streaming)
for await (const event of client.memories.recallStreaming({
  query: "What do I like?",
  token_budget: 500,
})) {
  if (event.type === "fact_retrieved") {
    console.log(`Found: ${event.preview}`);
  }
}

Entities

// List entities with pagination
const page = await client.entities.list({
  type: ["PERSON", "ORGANIZATION"],
  limit: 20,
  cursor: "optional-cursor",
});

// Auto-paginate through all entities
for await (const entity of client.entities.listAll({ type: ["PERSON"] })) {
  console.log(entity.name);
}

// Paginate by page
for await (const page of client.entities.listAll().byPage()) {
  console.log(`Page with ${page.data.length} items`);
}

// Get entity details
const entity = await client.entities.get("entity-uuid");

// Semantic search
const results = await client.entities.search({
  query: "technology companies",
  type: ["ORGANIZATION"],
  limit: 10,
});

// Get entity relationships
const relationships = await client.entities.getRelationships("entity-uuid");

// Get entity facts
const facts = await client.entities.getFacts("entity-uuid", {
  fact_type: "world",
});

Webhooks

// Create webhook
const webhook = await client.webhooks.create({
  url: "https://your-server.com/webhook",
  events: ["fact.created", "entity.created"],
  description: "My webhook",
});
console.log("Secret:", webhook.secret); // Store securely!

// List webhooks
const webhooks = await client.webhooks.list();

// Update webhook
await client.webhooks.update(webhookId, {
  events: ["fact.created", "fact.updated"],
  enabled: true,
});

// Test webhook
const testResult = await client.webhooks.test(webhookId);

// Rotate secret
const rotated = await client.webhooks.rotateSecret(webhookId);

// Get delivery history
const deliveries = await client.webhooks.getDeliveries(webhookId);

// Delete webhook
await client.webhooks.delete(webhookId);

Rate Limits

const status = await client.rateLimits.getStatus();
console.log(`Tier: ${status.tier}`);
console.log(`Remaining RPM: ${status.remaining.rpm}`);

Error Handling

import {
  Fidelius,
  FideliusError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  APIConnectionError,
  APITimeoutError,
} from "@fidelius-ai/sdk";

try {
  await client.agents.run({ message: "Hello" });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof NotFoundError) {
    // Resource not found
  } else if (error instanceof APITimeoutError) {
    // Request timed out
  } else if (error instanceof APIConnectionError) {
    // Network error
  } else if (error instanceof FideliusError) {
    // Other SDK error
  }
}

Idempotency

For POST requests, you can provide an idempotency key:

const result = await client.memories.ingest(request, {
  idempotencyKey: "unique-request-id",
});

TypeScript Support

All types are exported:

import type {
  AgentRunRequest,
  AgentRunResponse,
  SSEEvent,
  MemoryRecallRequest,
  MemoryRecallResponse,
  RecallStreamEvent,
  Entity,
  Webhook,
  Page,
} from "@fidelius-ai/sdk";

Requirements

• Node.js 18+
• Modern browsers with Fetch API support

License

MIT