@ciphyrs/sdk

Official Node.js SDK for Ciphyrs -- agent tracing, observability, and PII detection.

Installation

npm install @ciphyrs/sdk

Quick Start

Basic Tracing

import { CiphyrsClient } from '@ciphyrs/sdk';

const client = new CiphyrsClient({
  apiKey: 'ck_your_key',
  project: 'my-project',
});

await client.trace('research_pipeline', async (t) => {
  t.trigger_input = 'What is quantum computing?';

  const result = await client.span('Researcher', 'llm_call', async (s) => {
    s.setInput('What is quantum computing?');
    const answer = await llm.complete('What is quantum computing?');
    s.setOutput(answer);
    s.setTokens({ promptTokens: 50, completionTokens: 200 });
    return answer;
  });

  const summary = await client.span('Summarizer', 'llm_call', async (s) => {
    s.setInput(result);
    const out = await llm.complete(`Summarize: ${result}`);
    s.setOutput(out);
    return out;
  });

  t.final_output = summary;
});

Higher-Order Function Wrappers

import { CiphyrsClient, withTrace, withSpan, setDefaultClient } from '@ciphyrs/sdk';

const client = new CiphyrsClient({ apiKey: 'ck_your_key', project: 'my-project' });
setDefaultClient(client);

const research = withSpan('Researcher', 'llm_call', async (s, query) => {
  s.setInput(query);
  const result = await llm.complete(query);
  s.setOutput(result);
  return result;
});

const runPipeline = withTrace('research_task', async (t, query) => {
  t.trigger_input = query;
  const result = await research(query);
  t.final_output = result;
  return result;
});

await runPipeline('What is AI?');

OpenAI Auto-Tracing

import { CiphyrsClient } from '@ciphyrs/sdk';
import { patchOpenAI } from '@ciphyrs/sdk/integrations/openai';
import OpenAI from 'openai';

const ciphyrs = new CiphyrsClient({ apiKey: 'ck_your_key', project: 'my-project' });
const openai = new OpenAI();

patchOpenAI(openai, ciphyrs);

// All OpenAI calls inside a trace are automatically captured
await ciphyrs.trace('chat_pipeline', async () => {
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }],
  });
});

LangChain Integration

import { CiphyrsClient } from '@ciphyrs/sdk';
import { CiphyrsCallbackHandler } from '@ciphyrs/sdk/integrations/langchain';

const client = new CiphyrsClient({ apiKey: 'ck_your_key', project: 'my-project' });
const handler = new CiphyrsCallbackHandler({ client, traceName: 'langchain_run' });

const result = await chain.invoke(
  { input: 'What is AI?' },
  { callbacks: [handler] },
);

await handler.flush();

Direct Ingestion

const client = new CiphyrsClient({ apiKey: 'ck_your_key' });

await client.ingest(
  { name: 'my-project', framework: 'custom' },
  {
    trace_id: 'abc-123',
    name: 'my-trace',
    status: 'completed',
  },
  [
    {
      span_id: 'span-1',
      agent_name: 'MyAgent',
      kind: 'agent',
      input: 'hello',
      output: 'world',
      duration_ms: 150,
      status: 'ok',
    },
  ],
);

Span Kinds

| Kind | Description | |------|-------------| | agent | An autonomous agent step | | llm_call | A call to an LLM (OpenAI, Anthropic, etc.) | | tool_call | A tool/function invocation | | retrieval | A vector DB or search query |

Configuration

const client = new CiphyrsClient({
  apiKey: 'ck_your_key',
  baseUrl: 'https://api.ciphyrs.com',  // or self-hosted URL
  project: 'my-project',
  framework: 'langchain',
  maxBufferSize: 10,      // flush after 10 traces
  flushInterval: 30000,   // auto-flush every 30 seconds
  maxRetries: 3,          // retry failed requests
});

Context Propagation

The SDK uses Node.js AsyncLocalStorage for automatic context propagation. Spans created inside a trace() are automatically associated with it, and nested spans correctly track parent-child relationships -- even across async boundaries.

License

MIT