[NET-1093] feat: Add TTFT and RTTFT to LLM spans

.env.sample

@@ -10,9 +10,6 @@ NETRA_DISABLE_BATCH=
 # Debug Mode
 NETRA_DEBUG=
 
-# Root Span Configuration
-NETRA_ENABLE_ROOT_SPAN=
-
 # Scrubbing Configuration
 NETRA_ENABLE_SCRUBBING=
 

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).
 
+## [1.9.0] - Unreleased
+
+### Added
+
+- **Time to First Token (TTFT) & Relative TTFT**: All LLM generation spans now record `gen_ai.performance.time_to_first_token` (seconds from call start to first content chunk), `gen_ai.performance.relative_time_to_first_token` (seconds from trace root span start to first content chunk), and `gen_ai.performance.time_to_first_token.timestamp` (absolute ISO 8601 UTC time of first token). Supported across OpenAI, Anthropic, Groq, Mistral, Google GenAI, and Google Generative AI for both streaming and non-streaming calls. RTTFT is silently skipped when no root span exists.
+
+- **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.
+
+### 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.8.0] - 2026-08-03
 
 ### Added
@@ -124,7 +139,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: