feat: add Netra.redteam.runRedteam() to trigger an existing red-team config

.env.sample

@@ -31,3 +31,11 @@ NETRA_CONVERSATION_CONTENT_MAX_LEN=
 # ANTHROPIC_API_KEY=
 # GOOGLE_APPLICATION_CREDENTIALS=
 # GOOGLE_CLOUD_PROJECT=
+
+# Red-team SDK (Netra.redteam) — beta
+# Ordinary REST timeout (seconds) for every red-team API call (default: 20)
+NETRA_REDTEAM_TIMEOUT=
+# Interval (seconds) between createRun retries while prompts are still generating (default: 2)
+NETRA_REDTEAM_GENERATION_POLL_INTERVAL=
+# Deadline (seconds) to wait for prompt generation before failing (default: 300)
+NETRA_REDTEAM_GENERATION_TIMEOUT=

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Opt-in prompt caching** — `Netra.prompts.getPrompt()` accepts `useCache` and `cacheTtl`. When `useCache` is true, responses are served from an in-memory TTL cache (default TTL: `PROMPT_CACHE_TTL_SECONDS` = 60). Caching is off by default.
+- **Models API** — `Netra.models.getModelPricing()` fetches model pricing (optional `name` filter) with the same opt-in cache pattern (`useCache`, `cacheTtl`; default TTL: `MODEL_PRICING_CACHE_TTL_SECONDS` = 300).
+- **Cache lifecycle** — `Netra.shutdown()` clears prompts and models in-memory caches. `clearCache()` is also available on each client.
+- **Exported cache constants** — `PROMPT_CACHE_TTL_SECONDS` and `MODEL_PRICING_CACHE_TTL_SECONDS` are public exports.
+- **Red-team SDK (`Netra.redTeam`, beta)**: Trigger a red-team evaluation against a developer's local agent function via `Netra.redTeam.runRedTeam({ configId, task, maxConcurrency? })`. `configId` identifies a red-team config created ahead of time (e.g. in the dashboard) — the config's agent, evaluators, and attack settings are decided there; the SDK only drives the run. `task` is a plain callback `(prompt, sessionId, turnIndex) => Promise<string | {message, sessionId?}>`, called once per turn — no class to extend. The client fetches the run's whole generated prompt list once, then drives every session's turns itself (bounded local concurrency via `maxConcurrency`, default/cap 5), submitting each turn's result directly. Returns a `RedTeamResult` with `results`, `progress`, `riskScore`, and `runNumber` (matches the dashboard's "Run #N"). `Ctrl-C` (SIGINT/SIGTERM) reliably cancels any in-flight run server-side before the process exits — a single shared shutdown-hook registry replaces two independent signal listeners that could previously race each other.
+- **Trace Origin Label for Red-Team Runs**: Each red-team turn is now wrapped in its own span, with the root span carrying `netra.trace.origin = "redteam"` — the same mechanism already used for evaluation and simulation traces — so the backend can exclude red-team-originated traces from online evaluation, auto-evaluation, and insights enrichment.
+
+### Changed
+
+- **Prompt cache TTL** — Default TTL is the module constant `PROMPT_CACHE_TTL_SECONDS` (60). Override per call with `cacheTtl`. Removed unused `cacheTtlSeconds` init config and `NETRA_CACHE_TTL_SECONDS` env var.
+
 ## [1.9.0] - 2026-08-23
 
 ### Added
@@ -140,7 +155,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Context Propagation Helpers**: Exported `netraExpressMiddleware` and `runWithExtractedContext` for distributed tracing. These utilities extract incoming W3C Trace Context from HTTP headers and run code within that context, covering cases where auto-instrumentation is unavailable (ESM load-order issues, missing peer dependencies, or non-Express frameworks). 
+- **Context Propagation Helpers**: Exported `netraExpressMiddleware` and `runWithExtractedContext` for distributed tracing. These utilities extract incoming W3C Trace Context from HTTP headers and run code within that context, covering cases where auto-instrumentation is unavailable (ESM load-order issues, missing peer dependencies, or non-Express frameworks).
 
 ### Fixed
 

README.md

@@ -10,6 +10,7 @@
 - 🔧 **Multi-Provider Support**: Works with OpenAI, Google GenAI, Mistral, Anthropic, and more
 - 📈 **Session Management**: Track user sessions and custom attributes
 - 🌐 **Automatic Instrumentation**: Zero-code instrumentation for popular frameworks and libraries
+- ⚡ **Opt-in Read Caching**: In-memory TTL caching for read-heavy SDK calls (`getPrompt`, `getModelPricing`)
 
 ## 📦 Installation
 
@@ -184,6 +185,73 @@ async function generateContent(prompt: string) {
 }
 ```
 
+## 📝 Prompts API
+
+Fetch prompt versions from Prompt Studio via `Netra.prompts.getPrompt()`. Caching is **opt-in per call** — omit `useCache` (or set it to `false`) to always hit the API.
+
+Default TTL is **60 seconds** (`PROMPT_CACHE_TTL_SECONDS`). Override TTL for a single call with `cacheTtl`.
+
+```typescript
+import { Netra } from "netra-sdk";
+
+await Netra.init({
+  appName: "my-ai-app",
+});
+
+// Always fetches from the API (default)
+const prompt = await Netra.prompts.getPrompt({ name: "my-prompt" });
+
+// Cached for 60s (default TTL)
+const cached = await Netra.prompts.getPrompt({
+  name: "my-prompt",
+  useCache: true,
+});
+
+// Cached for 30s for this call only
+const shortLived = await Netra.prompts.getPrompt({
+  name: "my-prompt",
+  label: "production", // default label when omitted
+  useCache: true,
+  cacheTtl: 30,
+});
+```
+
+> **Note**: Cached prompts may be stale for up to the TTL after dashboard edits. Use `useCache: false` when you need the latest version immediately. `Netra.shutdown()` clears in-memory caches.
+
+## 💰 Models API
+
+Fetch model pricing via `Netra.models.getModelPricing()`. Caching is **opt-in per call** — omit `useCache` (or set it to `false`) to always hit the API.
+
+Default TTL is **300 seconds** (`MODEL_PRICING_CACHE_TTL_SECONDS`). Override TTL for a single call with `cacheTtl`.
+
+```typescript
+import { Netra } from "netra-sdk";
+
+await Netra.init({
+  appName: "my-ai-app",
+});
+
+// Always fetches from the API (default)
+const pricing = await Netra.models.getModelPricing();
+
+// Optional name filter
+const gptPricing = await Netra.models.getModelPricing({ name: "gpt-4o" });
+
+// Cached for 300s (default TTL)
+const cached = await Netra.models.getModelPricing({
+  useCache: true,
+});
+
+// Cached for 60s for this call only
+const shortLived = await Netra.models.getModelPricing({
+  name: "gpt-4o",
+  useCache: true,
+  cacheTtl: 60,
+});
+```
+
+> **Note**: Cached pricing may be stale for up to the TTL after dashboard edits. Use `useCache: false` when you need the latest values immediately. `Netra.shutdown()` clears in-memory caches.
+
 ## 🔧 Environment Variables
 
 You can configure the SDK using environment variables:
@@ -194,6 +262,9 @@ You can configure the SDK using environment variables:
 | `NETRA_APP_NAME` | Name of your application |
 | `NETRA_ENV` | Environment (e.g., prod, dev) |
 | `NETRA_TRACE_CONTENT` | Capture prompt/completion content (default: true) |
+| `NETRA_REDTEAM_TIMEOUT` | Red-team API request timeout in seconds — an ordinary, bounded REST timeout (default: `20`) |
+| `NETRA_REDTEAM_GENERATION_POLL_INTERVAL` | Interval in seconds between `createRun` retries while prompts are still generating (default: `2`) |
+| `NETRA_REDTEAM_GENERATION_TIMEOUT` | Deadline in seconds to wait for prompt generation to finish before failing (default: `300`) |
 
 ## 🤝 License