Interactive Platform Documentation
All 4 AI-BOM Automation Layers Documented

SHDWsdk Feature Reference & Engineering Documentation

Search across every feature in SHDWsdk—from non-blocking Scope 3 carbon telemetry and the 4 automated AI-BOM discovery layers to EU AI Act / NIST AI RMF documentation, CycloneDX / SPDX exports, customer statements, buyer requests and integrations.

Showing 22 of 22 guides
Getting Started & SDK
#cli#init#npx#shdw-init#wizard#env#boilerplate#connectivity

Interactive CLI Setup Wizard (npx @shdwsdk/sdk init / npx shdw-init)

Configure .env / .env.local, generate a ready-to-use AI client wrapper (src/lib/shdw.ts), and verify live telemetry connectivity in under 60 seconds.

How It Works Under the Hood
  • •Prompts interactively in your terminal for your SHDW API key (shdw_live_*), primary cloud data center region (22 EU/US/APAC/LATAM grids), and primary AI model (11 featured models; any model id works).
  • •Safely detects .env.local (or .env) and upserts SHDW_API_KEY and SHDW_GRID_REGION without modifying or overwriting any unrelated environment variables or comments.
  • •Generates a provider-tailored boilerplate file (default: src/lib/shdw.ts) pre-wired with ShdwTelemetryClient and shdw.wrapClient(), then sends a 1500ms-guarded validation ping to confirm your API key and network route.
How to Use It Step-by-Step
  1. 1Open your terminal in your project's root directory (Windows PowerShell, macOS Terminal, or Linux bash).
  2. 2Run `npx @shdwsdk/sdk init` (or `npx shdw-init`) and follow the 4 prompts.
  3. 3Import your wrapped AI client from `src/lib/shdw.ts` anywhere in your application.
Terminal — Interactive & Flag-Based Setup
# Interactive setup wizard
npx @shdwsdk/sdk init

# Or run directly with flags
npx shdw-init --api-key shdw_live_xxx --region eu-west-3 --model claude-sonnet-5-5 --out src/lib/shdw.ts
Getting Started & SDK
#wrapClient#sdk#openai#anthropic#gemini#sse#streaming#timeout#fail-silent#retry

Non-Blocking Client Wrapper (shdw.wrapClient) & Fail-Silent Guarantee

Wrap OpenAI, Anthropic or Google Gemini clients in one line of code with a strict 1500ms AbortController timeout and automatic 5xx retry buffering.

How It Works Under the Hood
  • •shdw.wrapClient(client) uses a lightweight JavaScript Proxy to observe .create(), .stream(), and .generateContent() calls without mutating your AI SDK client.
  • •For standard responses and Server-Sent Events (SSE) streams, @shdwsdk/sdk normalizes input and output token counts in memory and queues an event on a non-blocking microtask.
  • •Background network flushes use an AbortController strictly clamped to <= 1500ms. If a 5xx server error or network outage occurs and buffer capacity permits (< 450 events), failed batches are automatically unshifted back onto the buffer for retry.
How to Use It Step-by-Step
  1. 1Create an API key in Settings → Developer Settings & API Keys.
  2. 2Install @shdwsdk/sdk via npm, pnpm, yarn, or bun.
  3. 3Wrap your AI client instance with shdw.wrapClient() and use it normally across your application.
src/lib/ai.ts — Wrapping OpenAI & Anthropic
import OpenAI from "openai";
import { ShdwTelemetryClient } from "@shdwsdk/sdk";

const shdw = new ShdwTelemetryClient({
  apiKey: process.env.SHDW_API_KEY!,
  endpoint: "https://www.shdwsdk.ai/api/v1/ingest-telemetry",
  defaultGridRegion: "eu-north-1", // or "us-west-2"
  defaultWorkloadName: "Enterprise Support Copilot",
  timeoutMs: 1500,
});

export const openai = shdw.wrapClient(new OpenAI());
Automated AI-BOM (4 Layers)
#ai-bom#automation#prompt_hash_version#weights_hash#zero-knowledge#sha256#runtime#model_provenance

Layer 1: Zero-Touch Runtime AI-BOM Auto-Discovery & Zero-Knowledge Prompt Hashing

Automatically populate your AI Bill of Materials (AI-BOM) from live production AI calls without manually typing model versions or prompt hashes.

How It Works Under the Hood
  • •When your wrapped AI client makes a call, @shdwsdk/sdk inspects the request's system instructions (OpenAI system/developer messages, Anthropic system field, or Gemini systemInstruction) in memory.
  • •It computes a deterministic SHA-256 digest (prompt_hash_version) locally in ~0.04ms using Web Crypto. Your actual prompt text never leaves your server.
  • •The prompt_hash_version and exact model snapshot (e.g., claude-sonnet-5-5) piggyback on the existing telemetry ping (0 extra network requests). The ingest-telemetry Edge Function upserts your AI-BOM inventory. A weights_hash is recorded only if you send one for weights you host; hosted API vendors do not publish weight digests, so none are inferred.
How to Use It Step-by-Step
  1. 1No extra code is required beyond shdw.wrapClient(client).
  2. 2Optionally pass defaultWorkloadName and defaultEuAiRiskTier in ShdwTelemetryClient config to label the workload in your AI-BOM.
  3. 3Open the 'AI-BOM & Governance' tab in your Dashboard to view auto-discovered models and prompt version hashes.
Zero-Knowledge System Prompt Fingerprinting
// When your app calls openai.chat.completions.create():
const response = await openai.chat.completions.create({
  model: "gpt-5.4-mini",
  messages: [
    { role: "system", content: "You are a SOC2 security compliance assistant." },
    { role: "user", content: userQuestion },
  ],
});
// @shdwsdk/sdk hashes the system prompt in memory -> "sha256:8f41c9..."
// and auto-upserts (gpt-5.4-mini, sha256:8f41c9...) into your AI-BOM!
Automated AI-BOM (4 Layers)
#rag#vector-db#pinecone#pgvector#weaviate#qdrant#wrapVectorStore#embedding_model_id#spdx

Layer 2: RAG & Vector Database Auto-Instrumentation (shdw.wrapVectorStore)

Automatically link Pinecone, Supabase pgvector, Weaviate, Qdrant, and embedding models to your CycloneDX and SPDX 3.0 AI-BOM lineage graphs.

How It Works Under the Hood
  • •Calling shdw.wrapVectorStore(vectorClient, { sourceUrl, embeddingModelId }) registers your active vector knowledge base on the ShdwTelemetryClient instance.
  • •Every subsequent LLM telemetry event automatically includes vector_db_connected: true, vector_db_source_url, and embedding_model_id.
  • •When you export SPDX 3.0 AI Profile (.spdx.json) or CycloneDX v1.7 (.cdx.json), SHDWsdk automatically generates DatasetPackage nodes with dependsOn and trainedOn relationship edges.
How to Use It Step-by-Step
  1. 1Call shdw.wrapVectorStore() with your Pinecone index, Supabase client, or vector retriever.
  2. 2Specify the sourceUrl (e.g., https://index.pinecone.io/prod-kb or pgvector://supabase.db/documents) and embeddingModelId (e.g., text-embedding-3-large).
Auto-Instrumenting Pinecone or Supabase pgvector
import { Pinecone } from "@pinecone-database/pinecone";
import { ShdwTelemetryClient } from "@shdwsdk/sdk";

const shdw = new ShdwTelemetryClient({ apiKey: process.env.SHDW_API_KEY! });
const pc = new Pinecone({ apiKey: process.env.PINECONE_API_KEY! });

// Automatically links RAG dataset & embedding model to your AI-BOM
export const kbIndex = shdw.wrapVectorStore(pc.index("enterprise-contracts"), {
  sourceUrl: "https://index.pinecone.io/enterprise-contracts",
  embeddingModelId: "text-embedding-3-large",
  workloadName: "Contract RAG Copilot",
});
Automated AI-BOM (4 Layers)
#scanner#package.json#requirements.txt#ci-cd#github-actions#detectAiSdksInManifest#tree-shakeable

Layer 3: Static Manifest & CI/CD Auto-Scanner (@shdwsdk/sdk/scanner)

Scan package.json or requirements.txt with zero runtime overhead to auto-discover installed AI SDKs and Vector DB clients.

How It Works Under the Hood
  • •detectAiSdksInManifest() lives in a separate tree-shakeable entry point (@shdwsdk/sdk/scanner) so it adds nothing to your production bundle.
  • •It inspects package.json (Node.js/TypeScript) and requirements.txt (Python) for OpenAI, Anthropic, Gemini, Mistral and Cohere SDKs and Pinecone, pgvector, Weaviate, Qdrant and Chroma clients.
  • •A manifest tells you which vendors you use, not which model versions or endpoints, so the scanner reports vendors only. Confirm the exact model versions you call before adding them to your AI-BOM — or let the runtime SDK add them automatically.
How to Use It Step-by-Step
  1. 1Open the 'AI-BOM & Governance' tab, paste your package.json or requirements.txt and click 'Detect AI SDKs' to pre-fill the registration form, OR
  2. 2Import detectAiSdksInManifest from '@shdwsdk/sdk/scanner' in CI to flag AI SDKs that aren't yet in your AI-BOM.
CI manifest check
import fs from "node:fs";
import { detectAiSdksInManifest } from "@shdwsdk/sdk/scanner";

const { providers, vectorStores } = detectAiSdksInManifest({
  packageJsonContent: fs.readFileSync("./package.json", "utf8"),
});
console.log("AI SDKs:", providers, "Vector stores:", vectorStores);
Automated AI-BOM (4 Layers)
#cyclonedx#spdx#weights_hash#cdx.json#spdx.json#mistral#llama#deepseek#export

Layer 4: Model Integrity & CycloneDX / SPDX Exporters

How model identity, optional weight digests and measured energy are compiled into CycloneDX v1.7 (.cdx.json) and SPDX 3.0 (.spdx.json).

How It Works Under the Hood
  • •Hosted models (OpenAI, Anthropic, Google, …) are identified by provider and exact model version; their vendors do not publish weight digests. For models you host yourself, pass weightsHash ("sha256:<64 hex>") to record a digest you computed.
  • •compileCycloneDxMlBom() generates a CycloneDX v1.7 document with machine-learning-model components, SHA-256 hashes only where you supplied them, measured per-model energy/carbon, and RAG data dependencies.
  • •compileSpdx3AiBom() generates an SPDX 3.0.1 JSON-LD graph with ai_AIPackage nodes and, for RAG workloads, dataset_DatasetPackage nodes linked by dependsOn. Pass redactInfrastructure: true to replace vector store URLs with vendor names before sharing.
How to Use It Step-by-Step
  1. 1Go to the 'AI-BOM & Governance' tab of your dashboard.
  2. 2Click 'Export CycloneDX v1.7 (.cdx.json)' or 'Export SPDX 3.0 AI Profile (.spdx.json)' to download audit-ready files immediately.
Scope 3 Carbon & EU Regions
#scope-3#carbon#energy#kwh#gco2e#ecologits#ml-energy#eu#csrd#epa-egrid#regions

Scope 3 Energy & Carbon Formula + 22 Global & European Data Center Regions

How generated tokens, model size, datacenter PUE, and regional power grid intensity (EEA, Ember, US EPA eGRID) produce Scope 3 AI emissions estimates, with uncertainty ranges.

How It Works Under the Hood
  • •Inference Energy follows the open-source EcoLogits v0.11.3 methodology: GPU and server energy are modelled from the number of generated (output) tokens and the model's active and total parameter counts, then multiplied by the provider's datacenter PUE. Prompt tokens do not add energy in this methodology.
  • •Closed models (OpenAI, Anthropic, Google) don't publish parameter counts, so EcoLogits estimates them as ranges. Every reading stores a min, max and midpoint; dashboards report the midpoint.
  • •Each reading records how the model id was matched (exact, alias, normalized, family, or fallback). Unknown models use a wide generic frontier-class range and are flagged as fallback so they can be reviewed.
  • •Energy is recomputed on the server from token counts, so reported figures cannot be altered by the client.
  • •Scope 3 Carbon: C_scope3 (gCO2e) = E_inf (kWh) * Grid_Intensity (gCO2e/kWh).
  • •Supports 22 global regions including 10 European Union, EEA, UK & Swiss regions (Stockholm 28 gCO2e/kWh, Zurich 42, Paris 56, Madrid 162, London 207, Amsterdam 258, Dublin 274, Milan 296, Frankfurt 348, Warsaw 615) calibrated to EEA / Ember / CSRD ESRS E1, plus 6 North American (EPA eGRID) and 6 APAC/LATAM regions.
How to Use It Step-by-Step
  1. 1Choose your default grid region in Settings → Company & Account. It applies to telemetry that doesn't specify a region; set defaultGridRegion in the SDK to override it.
  2. 2Override region per AI request if needed by passing gridRegion: 'eu-west-3' in shdw.wrapClient(client, { gridRegion: 'eu-west-3' }).
EU AI Act & NIST AI RMF
#eu-ai-act#nist-rmf#govern#map#measure#manage#readiness-score#compliance#attestation

EU AI Act Risk Classification & US NIST AI RMF 1.0 Assessment Matrix

How your EU AI Act tier and 7 NIST AI RMF outcomes are documented: evidenced by telemetry where possible, otherwise self-attested.

How It Works Under the Hood
  • •SHDWsdk tracks 7 NIST AI RMF 1.0 subcategories (GOVERN 1.1, GOVERN 3.2, MAP 1.1, MAP 4.1, MEASURE 2.12, MANAGE 3.1, MANAGE 3.2). Four can be supported automatically by evidence (telemetry and AI-BOM coverage); policy outcomes such as GOVERN 1.1 can only be self-attested by your organization.
  • •Each control shows one of three statuses: evidence from telemetry, self-attested (with the date you saved it), or not documented. The AI RMF is voluntary guidance with no certification, so nothing is ever labelled 'verified'.
  • •Your EU AI Act risk tier is shown as self-declared.
How to Use It Step-by-Step
  1. 1Open the 'AI-BOM & Governance' tab of your dashboard.
  2. 2Select your organization's EU AI Act Risk Classification and check the active NIST AI RMF controls implemented by your team.
  3. 3Click 'Save self-attestation'. Your public trust report shows the attested controls with the date.
Public Trust Center & Badges
#trust-center#badge#iframe#rls#hash-chain#procurement#rfp#audit-trail

Buyer-Facing Public Trust Center (/trust/[slug]) & Embeddable HTML Badge

Share measured AI energy, emissions, your AI-BOM and governance documentation with buyers, backed by a hash-chained audit log — without exposing raw telemetry or infrastructure details.

How It Works Under the Hood
  • •Your trust report (shdwsdk.ai/trust/[your-slug]) shows 30-day estimated energy and emissions with uncertainty ranges, per-model usage, your AI-BOM, NIST AI RMF and EU AI Act documentation, and the integrity status of your audit log. It states clearly that the data is self-reported, not third-party audited.
  • •Visitors only receive an aggregated, sanitized report from the public-trust-data Edge Function: no billing or account identifiers, no vector store URLs, no raw telemetry rows. Anonymous database access is fully revoked.
  • •Every telemetry entry is linked into a SHA-256 hash chain when ingested and can't be edited afterwards; the report re-verifies the chain each time it is generated.
  • •Add a security contact email in Profile & Settings to show it on your report.
  • •When your organization has an active Starter, Scale or Enterprise subscription (including during a free trial), enterprise auditors can download your CycloneDX ML-BOM, SPDX 3.0 AI Profile, and Compliance Attestation directly from the Trust Report.
How to Use It Step-by-Step
  1. 1Open the 'Trust Badge' tab of your dashboard to copy the <iframe> embed snippet for your website footer or security portal.
  2. 2Click 'Trust report' in the top navigation bar to preview what enterprise buyers see.
Security & Rate Limiting
#security#api-keys#rate-limiting#sliding-window#stripe-webhook#timingSafeEqual#rls

API Key Encryption, Sliding-Window Rate Limiting & Constant-Time Webhooks

How SHDWsdk protects your telemetry pipeline against key compromise, flood attacks, and timing side-channels.

How It Works Under the Hood
  • •Raw API keys (shdw_live_*) are shown only once at creation; only their SHA-256 digest (key_hash) is stored in PostgreSQL.
  • •The ingest-telemetry Edge Function enforces a dual-layer sliding-window rate limit (120 requests / 60s per organization, 600 for partner keys) combining isolate-local burst rejection with the atomic PostgreSQL RPC check_and_increment_ingest_rate_limit, returning HTTP 429 with Retry-After headers on flood attempts.
  • •Stripe billing webhooks verify HMAC-SHA256 signatures using a constant-time byte comparison helper (timingSafeEqual) and a 300-second replay window guard.
How to Use It Step-by-Step
  1. 1Create and rotate API keys in Settings → Developer Settings & API Keys.
  2. 2Keep your raw shdw_live_* key in server-side environment variables (never expose service keys in client-side code).
Integrations & Data Sources
#python#pip#otel#opentelemetry#otlp#litellm#gen_ai#collector

Python SDK, OpenTelemetry and LiteLLM

Send telemetry without the JavaScript SDK: a Python package, a LiteLLM callback, or existing OpenTelemetry GenAI spans.

How It Works Under the Hood
  • •All integrations send only model ids and token counts. Energy and carbon are always recomputed on the server with the same EcoLogits methodology, so every source produces comparable figures.
  • •Python: shdwsdk.instrument(client) wraps OpenAI and Anthropic clients (sync, async and streaming). Events are sent from a background thread with a 1.5s timeout and never raise into your code.
  • •OpenTelemetry: POST OTLP/HTTP JSON traces to /api/v1/otlp/v1/traces with an x-shdw-key header. Spans with gen_ai.request.model or gen_ai.response.model and gen_ai.usage.* token counts are ingested; other spans are ignored. Protobuf encoding isn't supported.
  • •LiteLLM: ShdwLiteLLMLogger is a CustomLogger; add it to litellm.callbacks or reference shdwsdk.integrations.litellm.proxy_handler_instance in the proxy config.
  • •The dashboard's Data completeness card shows how many requests came from each integration.
How to Use It Step-by-Step
  1. 1Python: pip install shdwsdk, set SHDW_API_KEY, call shdwsdk.init() and shdwsdk.instrument(OpenAI()).
  2. 2OpenTelemetry: set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/json and the x-shdw-key header (see the install guide).
  3. 3If two instrumentations record the same call, keep only one so usage isn't counted twice.
Python
import shdwsdk
from openai import OpenAI

shdwsdk.init()                       # reads SHDW_API_KEY
client = shdwsdk.instrument(OpenAI())
Integrations & Data Sources
#coverage#completeness#reconciliation#billing#usage

Data completeness: reconcile with provider billing

Show buyers what share of your AI usage SHDWsdk captures by comparing captured tokens with your provider's billed totals.

How It Works Under the Hood
  • •You enter the total tokens (input + output) your provider billed for a period of up to 92 days. SHDWsdk compares it with the tokens captured for that provider in the same period.
  • •The latest result per provider appears on your public trust page as '% of billed tokens captured'. Notes stay private.
  • •If captured usage is below 95%, an alert can notify you (Integrations → Alerts).
How to Use It Step-by-Step
  1. 1Copy the token total from your provider's usage page for a period.
  2. 2On the dashboard Overview, click 'Reconcile with provider usage' and enter provider, period and tokens.
Integrations & Data Sources
#alerts#slack#webhook#hmac#signature#notifications

Alerts: Slack and signed webhooks

Get notified about buyer requests, telemetry gaps, audit-chain failures, low coverage and new models.

How It Works Under the Hood
  • •Disclosure requests are sent immediately. Other checks run on a daily schedule: no telemetry for 24 hours, audit chain break, coverage below 95%, and a new model in production.
  • •Each event is delivered once per destination; failed deliveries are retried on the next run.
  • •Webhooks receive JSON with X-SHDW-Event and X-SHDW-Signature: sha256=<hex HMAC-SHA256 of the raw body>, keyed with the destination's signing secret shown in the dashboard.
  • •Destination URLs must be public HTTPS hosts; Slack destinations must be hooks.slack.com incoming webhooks.
How to Use It Step-by-Step
  1. 1Open Integrations → Alerts → Add destination, choose Slack or webhook and the events.
  2. 2Click Test to send a sample alert.
  3. 3For webhooks, verify the signature before trusting the payload.
Verify a webhook (Node.js)
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyShdwSignature(rawBody: string, header: string, secret: string) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return header.length === expected.length &&
    timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}
Integrations & Data Sources
#developer#console#monitoring#drops#rejections#latency#debug#live

Developer console: pipeline health, drop rates and live events

See what arrives, what's rejected and why, what SDKs drop, when traffic peaks, and a live feed of events.

How It Works Under the Hood
  • •Every ingestion request is counted per hour as accepted or rejected, with the reason: revoked key, rate limited, invalid payload, batch too large or server error. Requests using a revoked key are attributed to that key, so you can see which deployment still has it. Keys that never existed can't be linked to an organization and aren't shown.
  • •JS SDK 1.8+ and Python SDK 0.2+ send delivery counters with their normal batches (about once a minute) or on their own every five minutes when idle: events delivered, dropped by reason (buffer full, key rejected, payload rejected, unreachable) and retried. That's where the drop rate comes from; it can't be measured from the server alone.
  • •Reports contain counters only, never event contents. Turn them off with deliveryReports: false (JS), delivery_reports=False (Python) or SHDW_DELIVERY_REPORTS=0.
  • •The console refreshes every 30 seconds (events every 10) while the tab is visible. Peaks and the hot-spot heat map use your local time zone.
How to Use It Step-by-Step
  1. 1Open Settings → Developer Settings & API Keys → Open console, or press g then d anywhere in the app.
  2. 2Check the status bar: Healthy, Degraded (more than 2% rejected or 1% dropped in 24 hours) or Stalled (nothing for 24 hours).
  3. 3Follow the suggested fix next to each rejection reason; outdated SDK versions are flagged in the integrations list.
Upgrade to get drop rates
npm install @shdwsdk/sdk@^1.8.0
pip install -U "shdwsdk>=0.2.0"

// Opt out of delivery counters (JS)
new ShdwTelemetryClient({ apiKey, deliveryReports: false });
Integrations & Data Sources
#csv#export#watershed#persefoni#sweep#savings#cost#pricing

Carbon accounting export and cost/carbon savings

Monthly activity CSV for carbon accounting tools, and estimates of what switching models would save.

How It Works Under the Hood
  • •The CSV has one row per month, provider, model and grid region with requests, tokens, electricity (with range), grid factor and kgCO2e, labelled Scope 3 Category 1. It's a generic format to map in your tool's importer, not a native integration.
  • •The Savings tab applies list prices (checked on the providers' pricing pages) to your actual token volumes and estimates the cost and emissions of moving a share of traffic to a smaller or newer model. It doesn't assess output quality.
How to Use It Step-by-Step
  1. 1Integrations → Carbon accounting export: choose a period and download the CSV (paid plans).
  2. 2Savings tab: pick an alternative model and a share of traffic; enter prices for models without a list price.
Customer Statements & Buyer Requests
#customer#customerRef#customer_ref#statement#scope-3#sb-253#allocation

Per-customer Scope 3 emissions statements

Attribute AI calls to the customer they serve and issue each customer a statement of the AI emissions allocated to them.

How It Works Under the Hood
  • •Each telemetry event can carry a customer_ref: your own pseudonymous account id for the customer (emails are rejected).
  • •The customer reference is part of the entry's audit hash, so re-attributing a call to a different customer breaks chain verification.
  • •Statements include allocated emissions and electricity with ranges, per-model and grid breakdowns, methodology, a statement ID (SHA-256 of its data) and the audit chain head.
How to Use It Step-by-Step
  1. 1JavaScript: pass customerRef per call, or resolveCustomerRef in the client config (e.g. from AsyncLocalStorage).
  2. 2Python: wrap calls in with shdwsdk.customer(account_id):. OpenTelemetry: set the shdw.customer_ref span attribute. LiteLLM: metadata={'shdw_customer_ref': account_id}.
  3. 3Open the 'Customer statements' tab, choose a period, optionally give customers display names, and open a statement (paid plans).
JavaScript
const shdw = new ShdwTelemetryClient({
  apiKey: process.env.SHDW_API_KEY!,
  resolveCustomerRef: () => requestContext.getStore()?.accountId,
});
Customer Statements & Buyer Requests
#questionnaire#rfp#security review#disclosure#request#buyer#procurement

Questionnaire answers and buyer disclosure requests

Draft answers to AI security questions from your data, and handle buyers' requests for your AI documentation.

How It Works Under the Hood
  • •The Questionnaire tab drafts answers to 21 common AI questions from your AI-BOM, telemetry, audit log, governance attestations and coverage. Each answer is marked 'Backed by your data', 'Draft: complete the blanks' or 'Needs your input'; policy questions are never answered for you.
  • •Edits are saved for your whole team. Export answers as CSV or Markdown on paid plans.
  • •Buyers can click 'Request documents' on your trust page; requests appear in the Requests tab and buyers see your response on their request page. Buyers can also ask vendors that aren't on SHDWsdk at shdwsdk.ai/request.
How to Use It Step-by-Step
  1. 1Open the Questionnaire tab, fill in the blanks, and copy or export answers.
  2. 2Add a Slack alert for disclosure requests in Integrations → Alerts, then answer them in the Requests tab.
Integrations & Data Sources
#coverage#azure#bedrock#vertex#self-hosted#on-premises#private cloud#vllm#ollama#embeddings#transcription#air-gapped

Deployment and model coverage: clouds, private hosting and self-hosted models

Which providers, hosting setups and model types SHDWsdk measures, how unknown models are handled, and what private-cloud and on-premises deployments need.

How It Works Under the Hood
  • •Any vendor: the model vendor (OpenAI, Anthropic, Google, Mistral, Cohere, Meta, DeepSeek, Alibaba, Microsoft, Amazon, xAI, or any other id) is recorded separately from where the model ran: vendor API, Azure, AWS Bedrock, Google Vertex, self-hosted or other. Hosting is detected from OpenTelemetry gen_ai.provider.name, LiteLLM routes and Bedrock/Vertex model ids, or set explicitly.
  • •Capture paths: the JavaScript and Python SDKs, LiteLLM (every provider it routes to, including Azure, Bedrock, Vertex, Ollama and vLLM), any OpenAI-compatible client, and OpenTelemetry. OTLP spans are read with the GenAI semantic conventions, so an OpenTelemetry Collector inside a private cloud can forward spans with no application changes.
  • •Energy for text generation uses EcoLogits (0.11.3), including open-weight models such as Llama, Mistral, Qwen and Gemma. Models not in the catalog (fine-tunes, renamed deployments) get a wide generic range and are flagged 'fallback' so they can be reviewed. Embeddings, reranking, moderation and transcription use a documented FLOP-based estimate (shdw-flops-v1); image, speech and OCR calls are counted but not yet estimated, and are excluded from emissions rather than reported as zero.
  • •Self-hosted models: set your datacenter's PUE in Settings → Developer and send a grid region or a measured gCO2e/kWh, so self-hosted calls aren't charged a cloud provider's efficiency.
  • •Private cloud and on-premises: only metadata leaves your network (model id, token counts, timing, region, pseudonymous ids), never prompts or outputs, through a single outbound HTTPS endpoint. Fully air-gapped installations without any outbound connection aren't supported today.
  • •Data regions: choose the United States (Oregon) or the European Union (Frankfurt). EU organizations send to the /eu/ endpoints.
How to Use It Step-by-Step
  1. 1Pick a capture path: SDK, LiteLLM, or an OpenTelemetry Collector exporting to /api/v1/otlp/v1/traces with your key.
  2. 2Set hosting (e.g. azure or self_hosted) if it can't be detected, and your PUE for self-hosted models.
  3. 3Check the Overview tab's coverage card and the developer console: fallback-matched models and dropped events show there.
OpenTelemetry Collector in a private cloud
exporters:
  otlphttp/shdw:
    traces_endpoint: https://www.shdwsdk.ai/eu/api/v1/otlp/v1/traces   # or /api/v1/... for US
    encoding: json
    headers:
      x-shdw-key: ${env:SHDW_API_KEY}
processors:
  attributes/shdw:
    actions:
      - { key: shdw.hosting, value: azure, action: upsert }   # or self_hosted
service:
  pipelines:
    traces/shdw:
      receivers: [otlp]
      processors: [attributes/shdw]
      exporters: [otlphttp/shdw]
Security & Rate Limiting
#security#mfa#sso#saml#data residency#subprocessors#gdpr#dpa#encryption#soc 2#iso 27001

Security and data handling: sign-in, regions, subprocessors, retention

What SHDWsdk stores, where it's stored, who processes it, how access is controlled, and how long it's kept.

How It Works Under the Hood
  • •Data collected: model ids, vendor and hosting, token counts, timing, grid region, energy and cost estimates, and your own pseudonymous customer, matter and trace ids. SHDWsdk never receives prompts, completions or documents, and rejects emails in attribution fields.
  • •Sign-in: two-factor authentication with any authenticator app, and SAML 2.0 single sign-on (Okta, Microsoft Entra ID, Google Workspace and others). An organization can require MFA, SSO or both; the database enforces it on every request, including the API. The owner keeps password access as a break-glass account.
  • •Isolation: every table is protected by PostgreSQL row-level security scoped to the organization; API keys are stored only as SHA-256 digests; the audit log is append-only and hash-chained.
  • •Regions: United States (AWS us-west-2, Oregon) or European Union (AWS eu-central-1, Frankfurt). Data is encrypted in transit (TLS 1.2+) and at rest (AES-256).
  • •Subprocessors: Supabase (database, authentication, functions; in your data region), Vercel (web hosting and API routing; global edge), Resend (transactional email; US), Stripe (billing; US, billing data only). The current list is published at shdwsdk.ai/docs/security-and-data-handling.
  • •Retention: keep everything, or 13 months to 10 years with a verifiable audit log; legal hold; export at any time; deletion 30 days after the owner schedules it.
  • •Attestations: SHDWsdk does not yet hold a SOC 2 report or ISO 27001 certificate. A data processing agreement and our controls documentation are available on request at security@shdwsdk.ai.
How to Use It Step-by-Step
  1. 1Turn on two-factor in Settings → Security, then require it for your organization.
  2. 2To use SSO, send your IdP's SAML metadata URL to security@shdwsdk.ai, then enter your domain in Settings → Security.
  3. 3Set retention and legal hold in Settings → Data.
Customer Statements & Buyer Requests
#matter#project#workflow#trace#agent#cost#pricing#attribution#law firm

Matters, workflows and cost: attribution below the customer

Break usage, cost and emissions down by your customer's matters or projects, and total each multi-step agent run.

How It Works Under the Hood
  • •customer_ref identifies your customer; matter_ref identifies a matter, case or project under that customer. Both must be pseudonymous ids (letters, digits and . _ : / -), never emails or names.
  • •trace_id groups every call of one agent run; workflow_name says which workflow it was. OpenTelemetry trace ids and gen_ai.agent.name are used automatically.
  • •Cost per call uses your own negotiated prices where you've set them in Settings → Developer, otherwise list prices; the longest matching model id wins. Calls without a price are counted as unpriced, never as free. Cost is stored per call but kept outside the audit chain, so correcting a price never breaks the evidence.
  • •The Usage & cost tab totals calls, tokens, emissions and cost by model, vendor, hosting, operation, customer, matter or workflow for the last 30 days.
How to Use It Step-by-Step
  1. 1Return customerRef, matterRef, workflowName and traceId from resolveContext (JavaScript), or use shdwsdk.matter() and shdwsdk.workflow() (Python).
  2. 2Add your negotiated prices in Settings → Developer → Model prices.
  3. 3Open Dashboard → Usage & cost and group by Matter or Workflow.
JavaScript and Python
// JavaScript
const shdw = new ShdwTelemetryClient({
  apiKey: process.env.SHDW_API_KEY,
  resolveContext: () => ({
    customerRef: ctx.firmId,
    matterRef: ctx.matterId,
    workflowName: ctx.workflow,
    traceId: ctx.traceId,
  }),
});

# Python
with shdwsdk.matter("M-2026-0042", customer_ref="firm-42"), shdwsdk.workflow("Due diligence"):
    run_agent()
Integrations & Data Sources
#partner#oem#platform#multi-tenant#client organizations#org_slug#reseller

Partner accounts: SHDWsdk for every customer of your platform

Platforms can give each of their customers their own SHDWsdk organization, trust page and statements, managed from one account and fed by one key.

How It Works Under the Hood
  • •A partner account manages client organizations. Each client has its own audit log, AI-BOM, statements, sign-in policy and trust page (private until published).
  • •Partner owners and admins administer every client. A client's MFA requirement applies to them; a client's SSO requirement doesn't, because they sign in through the partner.
  • •One partner key sends data for every client: each event carries org_slug. Each client has its own audit chain and rate limit, and an unknown slug is rejected rather than written anywhere else. Partner keys get five times the request rate.
  • •Clients inherit the partner's plan and follow it when it changes.
How to Use It Step-by-Step
  1. 1Ask us to enable partner access for your organization (partners@shdwsdk.ai).
  2. 2Add client organizations in Dashboard → Clients.
  3. 3Send each client's events with your partner key and org_slug set to the client's slug.
Routing events to a client organization
// JavaScript
resolveContext: () => ({ orgSlug: tenant.shdwSlug, customerRef: tenant.id })

# Python
with shdwsdk.organization("firm-one"):
    ...

# OpenTelemetry attribute
shdw.org_slug = "firm-one"
Security & Rate Limiting
#retention#legal hold#export#deletion#gdpr#audit log#checkpoint#csv

Data retention, legal hold, export and deletion

Choose how long the audit log is kept without losing verifiability, pause deletion for litigation, and export or delete everything.

How It Works Under the Hood
  • •Retention: keep everything, or between 13 months and 10 years. A daily job removes older entries from the start of the chain and records a checkpoint with the last removed entry's hash and the totals removed. Verification continues from the checkpoint, so the remaining log stays tamper-evident.
  • •Legal hold stops all pruning and deletion until the owner releases it.
  • •Export downloads the whole audit log as CSV in chain order with each entry's hash, plus a manifest with the chain head and verification result.
  • •Deletion: the owner types the organization's slug to schedule deletion of the organization and all its data 30 days later; owners or admins can cancel until then.
How to Use It Step-by-Step
  1. 1Open Settings → Data.
  2. 2Pick a retention period or turn on legal hold, then save.
  3. 3Use Download CSV + manifest before any deletion if you need a copy.