@semanticguard/ai-sdk

Guard your agents. Cut your LLM bill in half. 1 line of code.

Two features in one package:

1. Semantic caching + cost tracking for any AI provider via a custom fetch wrapper (withSemanticGuard).
2. Claude Code guardrails CLI (sg-guardrails-install + sg-guardrails-hook) that blocks destructive tool calls with a PreToolUse hook.

Install

npm install @semanticguard/ai-sdk

Claude Code guardrails (one-liner)

Blocks destructive tool calls (rm -rf, drop table, git push --force, PRs to main, terraform apply) using your tenant's policy engine.

npx --package=@semanticguard/ai-sdk sg-guardrails-install
export SG_API_KEY=sg-your-key-here      # get one at https://semanticguard.dev/dashboard/keys
export SG_WORKSPACE_TAG=prod            # optional attribution
export SG_GUARDRAILS_MODE=enforce       # or "warn" | "observe" for rollout

That's it. Every tool call now shows up in your /dashboard/agents audit feed with a policy verdict. Fail-open on any error so a guardrails outage never blocks a developer. Uninstall with the same command plus uninstall.

Semantic caching (SDK wrapper)

Add fetch: withSemanticGuard(...) to any AI SDK provider:

Google Vertex AI

import { createVertex } from "@ai-sdk/google-vertex";
import { withSemanticGuard } from "@semanticguard/ai-sdk";

const vertex = createVertex({
  project: "your-gcp-project",
  location: "us-central1",
  fetch: withSemanticGuard({
    gatewayUrl: "https://your-sg-instance.vercel.app",
  }),
});

OpenAI

import { createOpenAI } from "@ai-sdk/openai";
import { withSemanticGuard } from "@semanticguard/ai-sdk";

const openai = createOpenAI({
  apiKey: "your-openai-key",
  fetch: withSemanticGuard({
    gatewayUrl: "https://your-sg-instance.vercel.app",
  }),
});

Anthropic

import { createAnthropic } from "@ai-sdk/anthropic";
import { withSemanticGuard } from "@semanticguard/ai-sdk";

const anthropic = createAnthropic({
  apiKey: "your-anthropic-key",
  fetch: withSemanticGuard({
    gatewayUrl: "https://your-sg-instance.vercel.app",
  }),
});

How It Works

withSemanticGuard() returns a custom fetch function that:

1. Intercepts AI API calls (POST to model endpoints)
2. Routes them through SemanticGuard's passthrough proxy
3. The proxy checks exact match cache, then semantic cache (embedding similarity)
4. On cache hit: returns cached response instantly (no upstream call)
5. On cache miss: forwards to the provider, caches the response, logs metadata

Non-AI requests (GET, non-model endpoints) pass through directly without proxying.

Options

withSemanticGuard({
  gatewayUrl: "https://...",    // Your SemanticGuard instance URL (or set SEMANTICGUARD_URL env var)
  apiKey: "sg-...",             // SemanticGuard API key (or set SG_API_KEY env var)
  projectId: "my-project",     // Optional -- project ID for per-project isolation
  enabled: true,                // Optional -- toggle on/off (default: true)
  failOpen: true,               // Optional -- fall back to direct provider call if gateway is down (default: false)
  gatewayTimeoutMs: 10000,      // Optional -- timeout before fail-open kicks in, in ms (default: 10000)
  onLog: (entry) => { ... },   // Optional -- callback for each proxied request
});

Production configuration

For production, enable failOpen so your app continues working if the gateway is unreachable:

const openai = createOpenAI({
  apiKey: "sk-...",
  fetch: withSemanticGuard({
    failOpen: true,
    gatewayTimeoutMs: 5000,
  }),
});

When failOpen is true and the gateway returns a 429/5xx or times out, the SDK retries the request directly against your AI provider. The onLog callback receives a type: "fail-open" entry so you can track these events.

Data Flow

Requests are routed through SemanticGuard for caching and analytics. Prompts and responses are processed in-memory and cached according to your tenant settings. You can control what is stored via the dashboard:

• Cache learning -- toggle whether responses are cached for future matching
• Prompt storage -- toggle whether prompt text is persisted in request logs
• Semantic cache -- toggle vector-based similarity matching on or off

Metadata always logged: model name, token counts, latency, cache status, cost estimate.

Zero Dependencies

This package has no runtime dependencies. It only uses globalThis.fetch.

License

MIT