TypeScript SDK Guide

The primary ClawPipe SDK. Install from npm and use with any Node.js or edge runtime.

Install

npm install clawpipe-ai

Full Configuration

Pass a ClawPipeConfig object to the constructor. All options except apiKey and projectId are optional.

Option	Type	Default	Description
apiKey	string	required	Your ClawPipe API key (cp_xxx)
projectId	string	required	Project identifier
gatewayUrl	string	https://api.clawpipe.ai/v1	Gateway endpoint URL
cacheTtlMs	number	300000	Cache time-to-live in ms (5 min)
enableBooster	boolean	true	Enable Agent Booster stage
enablePacker	boolean	true	Enable Context Packer stage
enableCache	boolean	true	Enable Semantic Cache stage
enableTrace	boolean	false	Enable pipeline stage tracing
localModelUrl	string	auto-detect	URL of a local LLM server
enableLocalFallback	boolean	false	Auto-detect local LLM servers
budgetCapUsd	number	undefined	Hard budget cap in USD
budgetWarnUsd	number	undefined	Soft budget warning threshold
rateLimitPerDay	number	tier default	Max calls per day
allowlist	AllowlistEntry[]	undefined	Permitted providers/models
denylist	AllowlistEntry[]	undefined	Blocked providers/models
enableAudit	boolean	false	Enable audit logging
auditTransport	function	console	Custom audit log handler
enableTelemetry	boolean	true	Enable telemetry tracking
circuitBreakerThreshold	number	5	Failures before circuit opens
circuitBreakerRecoveryMs	number	30000	Recovery time in ms

PromptOptions

Option	Type	Description
system	string	System prompt
maxTokens	number	Max output tokens
temperature	number	Sampling temperature (0-2)
model	string	Force a specific model
provider	string	Force a specific provider
taskType	string	Hint for the router (e.g. "code", "chat")

All Exports

Core Pipeline

import { ClawPipe, Booster, Packer, Cache, Router, Gateway } from 'clawpipe-ai';

Enterprise Features

import { Telemetry, Budget, RateLimiter, CircuitBreaker } from 'clawpipe-ai';
import { Allowlist, AuditLogger } from 'clawpipe-ai';

Advanced Modules

import { Swarm, SemanticCache, Rag, Voice } from 'clawpipe-ai';
import { Tracer, WeightStore, LocalProvider, LocalGateway } from 'clawpipe-ai';
import { OpenAICompat } from 'clawpipe-ai'; // OpenAI drop-in replacement

Type Exports

import type {
  ClawPipeConfig, PromptOptions, PipelineMeta, PipelineResult,
  TelemetrySnapshot, AllowlistEntry, AuditLogEntry, AuditTransport,
  GatewayResponse, BudgetStatus, RateLimitStatus, CircuitStatus,
  RouteDecision, PackResult, SwarmConfig, SwarmStrategy, SwarmResult,
  SwarmCandidate, SemanticCacheConfig, StageTrace, TraceEvent,
  StoredWeight, ChatCompletion, ChatCompletionMessage, Choice,
  CompletionUsage, OpenAIConfig, CreateParams,
} from 'clawpipe-ai';

Streaming

for await (const chunk of pipe.stream('Analyze this code', {
  system: 'You are a code reviewer',
})) {
  process.stdout.write(chunk);
}

Observability Methods

pipe.stats();          // TelemetrySnapshot: requests, cost, cache rate
pipe.budgetStatus();   // Budget: spent, cap, remaining, percent
pipe.rateLimitStatus();// Rate limits: remaining calls, reset time
pipe.circuitStatus();  // Provider health: state, failures per provider
pipe.auditLogs();      // Compliance: timestamped action log

CLI Usage

clawpipe prompt "What is 2+2"                         # Send a prompt
clawpipe prompt "Explain" --system "..." --trace     # With tracing
clawpipe test                                          # Test pipeline
clawpipe stats                                         # Telemetry
clawpipe export                                        # JSON telemetry
clawpipe config                                        # Show configuration

Pipeline Tracing

const pipe = new ClawPipe({ ...config, enableTrace: true });
const result = await pipe.prompt('Hello');
console.log(result.trace);
// --- trace:
//   Booster      0.1ms (result=pass-through)
//   Packer       0.3ms (savings=22%)
//   Cache        0.1ms (result=miss)
//   Router       0.2ms (model=deepseek:deepseek-chat)
//   Gateway    412.0ms (tokensOut=156)
//   Total      412.7ms

// Export as Perfetto JSON for visual analysis:
const tracer = new Tracer(true);
tracer.toPerfetto(); // Chrome-compatible trace format