@neureus/sdk

Installation

npm install @neureus/sdk

Import

import { Neureus } from '@neureus/sdk';

The SDK exports one entry point (".") — there are no subpath exports.

Neureus client

const client = new Neureus({
  apiKey: process.env.NEUREUS_API_KEY!,
  baseUrl?: 'https://app.neureus.ai',  // default
});

Methods

// AI Gateway
client.ai.chat({ messages, model?, temperature?, maxTokens? })          // → ChatOutput
client.ai.stream({ messages, model?, temperature?, maxTokens? })        // → StreamingChatResponse
client.ai.embeddings({ text })                                          // → EmbeddingsOutput
client.ai.models({ provider?, type? })                                  // → { models: ModelInfo[] }
client.ai.listProviders()                                               // → { providers: ProviderInfo[] }
client.ai.setProviderKey(provider, key)                                 // → { provider, configured }
client.ai.rotateProviderKey(provider, key)                              // → { provider, configured }
client.ai.deleteProviderKey(provider)                                   // → void

// RAG
client.rag.ingest({ url? | content, title? })        // → IngestOutput
client.rag.query({ query, topK? })                   // → QueryOutput
client.rag.documents()                               // → document list
client.rag.delete(documentId)                        // → void

// Agents
client.agents.create({ name, model, systemPrompt, tools? })
client.agents.run(agentId, { input, sessionId? })
client.agents.getRun(agentId, runId)

// Workflows
client.workflows.create({ name, steps })
client.workflows.execute(workflowId, { input })
client.workflows.getRun(workflowId, runId)

// Composite
client.composite.execute({ pattern, profile, input })

// Vectors
client.vectors.search({ query, topK? })
client.vectors.upsert(vectors)

// Monitoring
client.monitoring.health()

Streaming

Use client.ai.stream() for token-by-token output — it returns a StreamingChatResponse which is AsyncIterable<string>:

const stream = await client.ai.stream({
  messages: [{ role: 'user', content: 'Write a haiku about edge computing.' }],
  model: 'gpt-4o-mini',
});

for await (const token of stream) {
  process.stdout.write(token);
}

Note: client.ai.chat() is always non-streaming and returns a ChatOutput with a text field.

ChatOutput fields

{
  // Neureus flat fields
  content: string;             // response text
  toolCalls?: unknown[];
  reasoning?: string;
  latencyMs: number;
  costUsd: number;
  savingsMechanism: 'cache_hit' | 'batch' | 'prompt_cache' | 'preprocessing' | 'none';
  // OpenAI-compatible envelope
  id: string;
  model: string;
  choices: Array<{ message: { role: string; content: string }; finish_reason: string }>;
  usage: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
    inputTokens: number;   // Neureus aliases
    outputTokens: number;
  };
}

Error handling

All errors throw NeureuAPIError:

import { Neureus, NeureuAPIError } from '@neureus/sdk';

try {
  await client.ai.chat({ messages });
} catch (err) {
  if (err instanceof NeureuAPIError) {
    console.error(err.status, err.code, err.message);
  }
}

Enums

import { CompositePattern, CompositeProfile, VectorMetric } from '@neureus/sdk';

CompositePattern.Consensus    // 'consensus'
CompositeProfile.Healthcare   // 'healthcare'
VectorMetric.Cosine           // 'cosine'