@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/hi-IN/observability.md

@@ -0,0 +1,294 @@
+---
+title: "अवलोकनशीलता"
+description: "एजेंट ट्रेस, मूल्यांकन, फीडबैक, ए/बी प्रयोग और अंतर्निहित डैशबोर्ड - सभी शून्य कॉन्फ़िगरेशन के साथ।"
+---
+
+# एजेंट अवलोकनशीलता
+
+प्रत्येक एजेंट-नेटिव ऐप को बॉक्स से बाहर अवलोकन क्षमता मिलती है। ट्रेस, स्वचालित मूल्यांकन, उपयोगकर्ता प्रतिक्रिया और ए/बी प्रयोग शून्य कॉन्फ़िगरेशन के साथ काम करते हैं - सभी डेटा ऐप के अपने SQL डेटाबेस में रहता है।
+
+यह पेज _एजेंट गुणवत्ता_ मेट्रिक्स को कवर करता है: आपके डेटाबेस में संग्रहीत निशान, लागत, मूल्यांकन और फीडबैक। _उत्पाद_ विश्लेषण के लिए (आपके ऐप के इवेंट पोस्टहॉग/मिक्सपैनल/एम्प्लिट्यूड पर प्रवाहित हो रहे हैं), [Tracking](/docs/tracking) देखें।
+
+## तीन चीजें जिन्हें "मूल्यांकन"/"अवलोकनशीलता" कहा जाता है - मैं क्या चाहता हूं? {#which}
+
+इन तीन पृष्ठों को भ्रमित करना आसान है। आप जो प्रश्न पूछ रहे हैं उसके अनुसार चुनें:
+
+| पेज                                                    | यह जिस प्रश्न का उत्तर देता है                         | जब यह चलता है                                   | चिंता       |
+| ------------------------------------------------------ | ------------------------------------------------------ | ----------------------------------------------- | ----------- |
+| **अवलोकन योग्यता** (यह पृष्ठ, _Evals_ टैब)             | "मेरा वास्तविक उत्पादन कैसा रहा?"                      | निष्क्रिय, प्रत्येक रन के बाद (LLM-जज का नमूना) | गुणवत्ता    |
+| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`)          | "क्या एजेंट इस निश्चित इनपुट पर सही काम करता है?"      | सक्रिय, नियतात्मक, एक सीआई/तैनाती गेट           | गुणवत्ता    |
+| **[Observational Memory](/docs/observational-memory)** | "क्या यह लंबा धागा सस्ता और खिड़की के अंदर रह रहा है?" | लंबे धागों पर पृष्ठभूमि संघनन                   | लागत/संदर्भ |
+
+ऑब्जर्वेबिलिटी और सीआई इवल गेट दोनों _गुणवत्ता_ स्कोर करते हैं, लेकिन विपरीत छोर से - वास्तविक ट्रैफ़िक की निष्क्रिय पोस्ट-हॉक स्कोरिंग बनाम निश्चित इनपुट पर सक्रिय पास/असफल जांच। अवलोकन संबंधी स्मृति का गुणवत्ता से कोई संबंध नहीं है; यह टोकन लागत और संदर्भ-विंडो दबाव के बारे में है।
+
+## क्या स्वचालित रूप से कैप्चर किया जाता है {#captured}
+
+जब कोई उपयोगकर्ता संदेश भेजता है, तो फ्रेमवर्क स्वचालित रूप से रिकॉर्ड करता है:
+
+- **टोकन उपयोग** - इनपुट, आउटपुट, कैश रीड, कैश राइट
+- **लागत** - टोकन गणना और मॉडल मूल्य निर्धारण से गणना की गई
+- **विलंबता** — प्रति टूल कॉल की कुल अवधि और समय
+- **टूल कॉल** - कौन सा actions लागू किया गया, सफलता/त्रुटि स्थिति, अवधि
+- **स्वचालित मूल्यांकन** - प्रत्येक रन के बाद 5 गुणवत्ता स्कोर की गणना की जाती है
+
+कोई कोड परिवर्तन की आवश्यकता नहीं है। उपकरण पारदर्शी रूप से `production-agent.ts` से जुड़ जाता है।
+
+```an-diagram title="Every run feeds the loop" summary="One agent run produces a trace, automated scores, and a feedback hook — all stored in the app's own SQL and surfaced on the dashboard. Experiments split traffic across config variants."
+{
+  "html": "<div class=\"obs-loop\"><div class=\"diagram-node\">Agent run<br><small class=\"diagram-muted\">production-agent.ts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Captured automatically</span><small class=\"diagram-muted\">tokens &middot; cost &middot; latency &middot; tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Traces &amp; spans</div><div class=\"diagram-box\">Evals (5 scorers + LLM judge)</div><div class=\"diagram-box\">Feedback &amp; frustration index</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Dashboard<br><small class=\"diagram-muted\">scoped to the signed-in user</small></div></div>",
+  "css": ".obs-loop{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.obs-loop .diagram-col{display:flex;flex-direction:column;gap:8px}.obs-loop .diagram-arrow{font-size:22px;line-height:1}.obs-loop .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## डैशबोर्ड {#dashboard}
+
+एकल रूट वाले किसी भी टेम्पलेट में डैशबोर्ड जोड़ें:
+
+```tsx
+// app/routes/observability.tsx
+import { ObservabilityDashboard } from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+```
+
+सारा डेटा साइन-इन उपयोगकर्ता के दायरे में है; आज कोई क्रॉस-यूज़र एडमिन व्यू नहीं है।
+
+डैशबोर्ड में 5 टैब हैं:
+
+| टैब             | यह क्या दिखाता है                                                              |
+| --------------- | ------------------------------------------------------------------------------ |
+| **अवलोकन**      | मुख्य मेट्रिक्स - रन, लागत, विलंबता, उपकरण सफलता दर, संतुष्टि, मूल्यांकन स्कोर |
+| **बातचीत**      | अलग-अलग स्पैन (एजेंट*रन, एलएलएम*कॉल, टूल_कॉल) में ड्रिल-डाउन के साथ ट्रेस सूची |
+| **इवल्स**       | मानदंडों, समय के साथ रुझानों के आधार पर स्वचालित मूल्यांकन स्कोर               |
+| **प्रयोग**      | स्थिति बैज के साथ ए/बी परीक्षण सूची, आत्मविश्वास अंतराल के साथ भिन्न परिणाम    |
+| **प्रतिक्रिया** | अंगूठे ऊपर/नीचे स्ट्रीम, श्रेणी विश्लेषण, हताशा स्कोर                          |
+
+## उपयोगकर्ता प्रतिक्रिया {#feedback}
+
+### स्पष्ट प्रतिक्रिया
+
+अंगूठे ऊपर/नीचे बटन UI चैट में प्रत्येक एजेंट संदेश पर इनलाइन प्रस्तुत करते हैं। थम्स डाउन एक श्रेणी पॉपओवर खोलता है (गलत, मददगार नहीं, गलत टूल, बहुत धीमा)। यह स्वचालित रूप से `AssistantChat.tsx` में वायर्ड हो जाता है।
+
+### अंतर्निहित प्रतिक्रिया (निराशा सूचकांक)
+
+फ्रेमवर्क वार्तालाप संकेतों से निराशा सूचकांक (0-100) की गणना करता है:
+
+| सिग्नल                  | वजन | यह क्या पता लगाता है                            |
+| ----------------------- | --- | ----------------------------------------------- |
+| रीफ़्रेज़िंग            | 30% | उपयोगकर्ता समान संदेश दोहराता है                |
+| पैटर्न पुनः प्रयास करें | 20% | "पुनः प्रयास करें", "नहीं, यह गलत है"           |
+| परित्याग                | 20% | प्रतिक्रिया के तुरंत बाद सत्र समाप्त हो जाता है |
+| भावना                   | 15% | नकारात्मक भाषा पैटर्न                           |
+| लंबाई प्रवृत्ति         | 15% | संदेश की लंबाई कम करना                          |
+
+स्कोर व्याख्या: 0-20 = स्वस्थ, 20-40 = घर्षण, 40-60 = असंतुष्ट, 60+ = टूटा हुआ सत्र।
+
+## स्वचालित मूल्यांकन {#evals}
+
+प्रत्येक एजेंट के दौड़ने के बाद पांच नियतात्मक स्कोरर दौड़ते हैं:
+
+| मानदंड              | यह क्या मापता है                                                | स्कोर रेंज |
+| ------------------- | --------------------------------------------------------------- | ---------- |
+| `tool_success_rate` | % टूल कॉल बिना त्रुटियों के                                     | 0-1        |
+| `step_efficiency`   | टूल-उपयोग रन के लिए अत्यधिक LLM पुनरावृत्तियों को दंडित करता है | 0-1        |
+| `latency_score`     | 10s/टूल बेसलाइन के विरुद्ध सामान्यीकृत                          | 0-1        |
+| `cost_efficiency`   | लागत आधार रेखा के विरुद्ध सामान्यीकृत                           | 0-1        |
+| `error_recovery`    | क्या एजेंट टूल त्रुटियों से उबर गया?                            | 0 या 1     |
+
+### LLM-न्यायाधीश के रूप में (वैकल्पिक)
+
+`evalSampleRate` सेट करके नमूना LLM-आधारित मूल्यांकन सक्षम करें:
+
+```ts
+import { putSetting } from "@agent-native/core/settings";
+
+await putSetting("observability-config", {
+  enabled: true,
+  evalSampleRate: 0.05, // 5% of runs
+});
+```
+
+कस्टम मानदंड प्राकृतिक भाषा रूब्रिक्स का उपयोग करते हैं:
+
+```ts
+const criteria = {
+  name: "helpfulness",
+  description: "Was the response helpful and complete?",
+  rubric: "0.0 = unhelpful, 0.5 = partially helpful, 1.0 = fully resolved",
+};
+```
+
+## ए/बी प्रयोग {#experiments}
+
+विभिन्न मॉडलों, तापमानों या एजेंट कॉन्फ़िगरेशन का परीक्षण करें:
+
+```ts
+// Create via API
+POST /_agent-native/observability/experiments
+{
+  "name": "model-a-vs-b",
+  "variants": [
+    { "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
+    { "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
+  ],
+  "metrics": ["cost", "latency", "satisfaction"]
+}
+
+// Start the experiment
+PUT /_agent-native/observability/experiments/:id
+{ "status": "running" }
+```
+
+`<your-model-id>` / `<other-model-id>` के स्थान पर आपके इंजन द्वारा स्वीकार किए जाने वाले वास्तविक मॉडल पहचानकर्ताओं का उपयोग करें (मॉडल नाम अक्सर बदलते रहते हैं - वर्तमान आईडी के लिए अपने प्रदाता/इंजन की जांच करें)। एजेंट लूप स्वचालित रूप से उपयोगकर्ता के वेरिएंट का समाधान करता है और कॉन्फ़िगरेशन ओवरराइड लागू करता है। असाइनमेंट लगातार हैशिंग का उपयोग करता है - एक ही उपयोगकर्ता को हमेशा एक ही प्रकार मिलता है।
+
+```an-diagram title="Consistent-hash variant assignment" summary="Each user hashes to a stable variant, the loop applies that variant's config override, and results roll up per variant with confidence intervals."
+{
+  "html": "<div class=\"exp\"><div class=\"diagram-node\">User id<br><small class=\"diagram-muted\">consistent hash</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill\">control &middot; 50%</span><small class=\"diagram-muted\">config override A</small></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">treatment &middot; 50%</span><small class=\"diagram-muted\">config override B</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Results per variant<br><small class=\"diagram-muted\">cost &middot; latency &middot; satisfaction</small></div></div>",
+  "css": ".exp{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.exp .diagram-col{display:flex;flex-direction:column;gap:8px}.exp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.exp .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## कॉन्फ़िगरेशन {#config}
+
+सभी सेटिंग्स `observability-config` कुंजी में संग्रहीत हैं:
+
+```ts
+{
+  enabled: true,           // Master switch
+  capturePrompts: false,   // Store prompt content in traces
+  captureToolArgs: false,  // Store action input arguments
+  captureToolResults: false, // Store action results
+  evalSampleRate: 0,       // 0-1, fraction of runs to LLM-judge
+  exporters: []            // OTLP export targets
+}
+```
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Content is **redacted by default** — only token counts, costs, and timing are stored. `capturePrompts`, `captureToolArgs`, and `captureToolResults` are opt-in; turn them on only when you need prompt/argument content for debugging."
+}
+```
+
+## API समापन बिंदु {#api}
+
+`/_agent-native/observability/` पर सभी ऑटो-माउंटेड:
+
+| विधि | पथ                         | उद्देश्य                       |
+| ---- | -------------------------- | ------------------------------ |
+| GET  | `/`                        | अवलोकन आँकड़े                  |
+| GET  | `/traces`                  | सूची ट्रेस सारांश              |
+| GET  | `/traces/:runId`           | ट्रेस विवरण (सारांश + विस्तार) |
+| GET  | `/traces/:runId/evals`     | एक रन के लिए मूल्यांकन         |
+| POST | `/feedback`                | प्रतिक्रिया सबमिट करें         |
+| GET  | `/feedback`                | प्रतिक्रिया सूचीबद्ध करें      |
+| GET  | `/feedback/stats`          | प्रतिक्रिया एकत्रीकरण          |
+| GET  | `/satisfaction`            | संतुष्टि स्कोर                 |
+| GET  | `/evals/stats`             | समान आँकड़े                    |
+| POST | `/experiments`             | प्रयोग बनाएं                   |
+| GET  | `/experiments`             | प्रयोगों की सूची बनाएं         |
+| GET  | `/experiments/:id`         | प्रयोग विवरण प्राप्त करें      |
+| PUT  | `/experiments/:id`         | अद्यतन प्रयोग                  |
+| POST | `/experiments/:id/results` | परिणामों की गणना करें          |
+| GET  | `/experiments/:id/results` | परिणाम प्राप्त करें            |
+
+सभी समापन बिंदु `?since=N` (एमएस टाइमस्टैम्प) और `?limit=N` क्वेरी पैरामीटर का समर्थन करते हैं।
+
+## बाहरी प्लेटफ़ॉर्म पर निर्यात करें {#export}
+
+लैंगफ्यूज, डेटाडॉग, ग्राफाना, या किसी ओटेल-संगत बैकएंड पर निशान भेजें:
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  exporters: [
+    {
+      type: "otlp",
+      endpoint: "https://cloud.langfuse.com/api/public/otel",
+      headers: { Authorization: "Bearer sk-..." },
+    },
+  ],
+});
+```
+
+फ्रेमवर्क ओपनटेलीमेट्री जेनएआई स्पेक के साथ संगत `gen_ai.*` सिमेंटिक कन्वेंशन स्पैन का उत्सर्जन करता है।
+
+## ओपनटेलीमेट्री स्पैन {#otel}
+
+उपरोक्त `exporters` कॉन्फ़िगरेशन से अलग (जो इन-हाउस ट्रेस को OTLP एंडपॉइंट पर भेजता है), एजेंट लूप प्रत्येक रन, मॉडल कॉल और टूल कॉल के लिए **लाइव ओपनटेलीमेट्री स्पैन** भी उत्सर्जित कर सकता है - इसलिए एक होस्ट जो पहले से ही एक ओटेल कलेक्टर चलाता है, उसके बाकी वितरित ट्रेस के साथ एजेंट गतिविधि देखता है।
+
+यह परत **वैकल्पिक है और डिफ़ॉल्ट रूप से नो-ऑप है**:
+
+- `@opentelemetry/api` एक **वैकल्पिक निर्भरता** है। यदि इसे स्थापित नहीं किया गया है, तो हेल्पर्स साइलेंट नो-ऑप्स में बदल जाते हैं - यहां कुछ भी कभी भी एजेंट लूप में नहीं जाता है।
+- यहां तक कि जब एपीआई पैकेज मौजूद होता है, तब भी यह एक डिफ़ॉल्ट नो-ऑप ट्रेसर भेजता है। स्पैन तभी वास्तविक हो जाते हैं जब **होस्ट एक `TracerProvider`** पंजीकृत करता है (`@opentelemetry/sdk-node` या इसी तरह के माध्यम से)। फ्रेमवर्क जानबूझकर भारी SDK/निर्यातक पैकेजों पर निर्भर **नहीं** करता है या प्रदाता को स्वयं पंजीकृत नहीं करता है - इंस्ट्रुमेंटेशन एम्बेडिंग ऐप द्वारा ऑप्ट-इन किया जाता है।
+
+इसलिए जब आपने ओटेल को वायर्ड नहीं किया है तो प्रति कॉल कुछ कैश्ड प्रॉपर्टी पढ़ने की लागत आती है। इसे चालू करने के लिए, एपीआई पैकेज और अपना SDK इंस्टॉल करें और सर्वर स्टार्टअप पर एक प्रदाता को उसी तरह पंजीकृत करें जैसे आप किसी अन्य नोड सेवा के लिए करते हैं।
+
+एजेंट लूप तीन प्रकार के स्पैन उत्सर्जित करता है:
+
+| विस्तार     | कब                         | गुण                                                               |
+| ----------- | -------------------------- | ----------------------------------------------------------------- |
+| `agent.run` | प्रति एजेंट एक बार चलाएं   | `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model` |
+| `tool.call` | प्रति क्रिया एक बार आह्वान | `tool.name`, प्लस सफलता/त्रुटि स्थिति                             |
+| `llm.call`  | प्रति मॉडल कॉल             | समय + ठीक/त्रुटि स्थिति                                           |
+
+ओके/ERROR स्थिति के साथ स्पैन समाप्त हो जाते हैं और विफलता पर त्रुटि संदेश रिकॉर्ड करते हैं। शून्य/प्रहरी विशेषता मानों को काट दिया जाता है ताकि स्पैन शोर से अव्यवस्थित न हों। यह ओटेल परत पूरी तरह से इन-हाउस `agent_trace_spans` / `agent_trace_summaries` तालिकाओं से जुड़ी हुई है जो ऊपर डैशबोर्ड को शक्ति प्रदान करती हैं - दोनों एक ही रन इवेंट से निर्मित होते हैं।
+
+## त्रुटि रिपोर्टिंग (Sentry) {#sentry}
+
+DSN कॉन्फ़िगर होने पर Nitro रूट हैंडलर से बचने वाली सर्वर-साइड त्रुटियां Sentry को रिपोर्ट की जाती हैं। इसके बिना SDK चुपचाप नो-ऑप्स करता है, इसलिए env vars को dev में अनसेट छोड़ना सुरक्षित है। ब्राउज़र और सर्वर इवेंट एक ही Sentry प्रोजेक्ट पर जा सकते हैं; उन्हें अलग-अलग प्रोजेक्ट में तभी विभाजित करें जब आप स्वामित्व, वॉल्यूम, कोटा या अलर्ट रूटिंग के लिए परिचालन पृथक्करण चाहते हों।
+
+| सतह                | SDK               | पर्यावरण संस्करण                                               | नोट्स                                                                                  |
+| ------------------ | ----------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| ब्राउज़र / SPA     | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`, `SENTRY_CLIENT_DSN`, या `SENTRY_DSN` | क्लाइंट में अनहैंडल की गई त्रुटियों और रूट-चेंज ब्रेडक्रंब को कैप्चर करता है।          |
+| Nitro सर्वर        | `@sentry/node`    | `SENTRY_SERVER_DSN` या `SENTRY_DSN`                            | 5xx प्रतिक्रियाएँ और Nitro जीवनचक्र त्रुटियाँ कैप्चर करता है। प्रति-अनुरोध उपयोगकर्ता. |
+| `agent-native` CLI | `@sentry/node`    | _हार्डकोडेड_                                                   | प्रकाशित CLI बाइनरी से क्रैश रिपोर्ट; उपयोगकर्ता-कॉन्फ़िगर करने योग्य नहीं।            |
+
+### सर्वर-साइड कॉन्फ़िगरेशन {#sentry-config}
+
+परिनियोजन परिवेश में `SENTRY_SERVER_DSN` या साझा `SENTRY_DSN` सेट करें (नेटलिफाई डैशबोर्ड, क्लाउडफ्लेयर रहस्य, आदि)। फ्रेमवर्क एक Nitro प्लगइन को ऑटो-माउंट करता है जो:
+
+1. स्टार्टअप पर एक बार `Sentry.init` पर कॉल करता है (आइडेम्पोटेंट - कई प्लगइन्स से कॉल करने के लिए सुरक्षित)।
+2. प्रत्येक API/फ्रेमवर्क अनुरोध पर `getSession(event)` के माध्यम से उपयोगकर्ता का समाधान करता है और Sentry के प्रति-अनुरोध अलगाव दायरे में `id` / `email` / `username` प्लस एक `orgId` टैग जोड़ता है। अतिरिक्त DB हिट से बचने के लिए स्टेटिक-एसेट पथ को छोड़ दिया जाता है।
+3. हर फ्रेमवर्क-रूट 5xx को खोजने योग्य `route`, `method`, और `userAgent` टैग के साथ कैप्चर करता है।
+
+वैकल्पिक नॉब्स:
+
+- `SENTRY_SERVER_TRACES_SAMPLE_RATE` (फ्लोट `0`-`1`) - प्रदर्शन अनुरेखण में ऑप्ट इन करें। डिफ़ॉल्ट रूप से `0` (केवल त्रुटियाँ)। अमान्य मान `0` पर चिपक जाते हैं।
+- `AGENT_NATIVE_RELEASE` - `release` टैग को ओवरराइड करता है। डिफ़ॉल्ट रूप से `agent-native-server@<core-version>`.
+
+### टेम्पलेट्स
+
+प्रत्येक टेम्पलेट इसे स्वचालित रूप से प्राप्त करता है - आयात करने के लिए कुछ भी नहीं है। SSR ऐप्स के लिए, जब `SENTRY_CLIENT_DSN`, `VITE_SENTRY_CLIENT_DSN`, या साझा `SENTRY_DSN` रनटाइम पर उपलब्ध होता है, तो सर्वर एक छोटी ब्राउज़र कॉन्फिग स्क्रिप्ट इंजेक्ट करता है, इसलिए ब्राउज़र कैप्चर Vite बिल्ड-टाइम एनवी तक सीमित नहीं है। जो टेम्पलेट कस्टम व्यवहार चाहते हैं (अतिरिक्त टैग, प्रति टेम्पलेट अलग DSN, हार्ड-अक्षम Sentry) वे `server/plugins/sentry.ts` से अपना स्वयं का प्लगइन निर्यात करके ओवरराइड कर सकते हैं:
+
+```ts
+// server/plugins/sentry.ts
+import { createSentryPlugin } from "@agent-native/core/server";
+export default createSentryPlugin();
+```
+
+CLI का हार्डकोडेड DSN जानबूझकर किया गया है - प्रकाशित बाइनरी को होम क्रैश को फ़ोन करने की आवश्यकता है, चाहे कोई भी वातावरण इसे चलाता हो। सर्वर मॉड्यूल कभी भी DSN को हार्डकोड नहीं करता है क्योंकि यह ग्राहक वातावरण के अंदर चलता है जहां ऑपरेटर तय करते हैं कि त्रुटियां Sentry तक पहुंचनी चाहिए या नहीं।
+
+### गोपनीयता और PII {#privacy}
+
+सर्वर और CLI दोनों `sendDefaultPii: false` और एक `beforeSend` हुक के साथ प्रारंभ होते हैं जो स्ट्रिप करता है:
+
+- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
+- `request.cookies`
+- `user.ip_address` (सहमति के बिना स्वतः एकत्रित)
+- `contexts.runtime_env` (प्रक्रिया env स्नैपशॉट)
+- कोई भी घटना जिसका शीर्ष-स्तरीय अपवाद प्रकार `ValidationError` है (अपेक्षित उपयोगकर्ता-इनपुट अस्वीकृति के रूप में माना जाता है, बग नहीं)।
+
+`setUser({ id, email, username })` के माध्यम से स्पष्ट रूप से निर्धारित पहचान फ़ील्ड संरक्षित हैं।
+
+## आगे क्या है
+
+- [**Tracking**](/docs/tracking) - आपके ऐप के अपने इवेंट के लिए उत्पाद विश्लेषण (पोस्टहॉग, मिक्सपैनल, एम्प्लिट्यूड)
+- [**Actions**](/docs/actions) - वे ऑपरेशन जो ट्रेस में टूल कॉल के रूप में दिखाई देते हैं
+- [**Security**](/docs/security) - डेटा स्कोपिंग और क्रेडेंशियल हैंडलिंग

package/docs/content/locales/hi-IN/observational-memory.md

@@ -0,0 +1,77 @@
+---
+title: "अवलोकनात्मक स्मृति"
+description: "पृष्ठभूमि त्रि-स्तरीय संघनन (हालिया कच्चा → अवलोकन → प्रतिबिंब) जो छोटी बातचीत को छुए बिना लंबे एजेंट थ्रेड को सस्ता और त्वरित-कैश-स्थिर रखता है।"
+---
+
+# अवलोकनात्मक स्मृति
+
+एक लंबे समय तक चलने वाला एजेंट थ्रेड एक विशाल प्रतिलेख जमा करता है: प्रत्येक संदेश, प्रत्येक टूल कॉल, प्रत्येक परिणाम। प्रत्येक मोड़ पर उस पूरे इतिहास को मॉडल में दोहराना महंगा है और अंततः संदर्भ विंडो को नष्ट कर देता है। **ऑब्जर्वेशनल मेमोरी (ओएम)** एक लंबे धागे के पुराने हिस्से को दिनांकित, स्तरित सारांश में संकुचित करता है ताकि मॉडल को अभी भी पता चले कि क्या हुआ - टोकन लागत के एक अंश पर - जबकि सबसे हालिया मोड़ शब्दशः रहते हैं।
+
+ओएम पूरी तरह से स्वचालित और मालिक के दायरे में है। **छोटे धागे अप्रभावित रहते हैं**: जब तक कोई धागा पहली संघनन सीमा को पार नहीं कर लेता, OM एक नो-ऑप है और संदर्भ बाइट-दर-बाइट है कि यह इसके बिना क्या होगा।
+
+## तीन स्तर {#tiers}
+
+ओएम एक लंबे धागे को तीन परतों के रूप में दर्शाता है, सबसे आसुत से लेकर सबसे नवीनतम तक:
+
+| स्तर                   | यह क्या है                                                                                                     |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **प्रतिबिंब**          | उच्चतम-स्तर, बड़े होने पर अवलोकन लॉग से संघनित। लॉन्ग-आर्क सारांश.                                             |
+| **टिप्पणियाँ**         | सघन, दिनांकित प्रविष्टियाँ जो कच्चे संदेशों के एक खंड को घटित होने वाले एक संक्षिप्त रिकॉर्ड में बदल देती हैं। |
+| **हाल के कच्चे संदेश** | अंतिम एन मोड़, **शब्दशः** रखा गया - कभी मुड़ा नहीं - इसलिए एजेंट हमेशा नवीनतम संदर्भ देखता है।                 |
+
+```an-diagram title="Three tiers, distilled to recent" summary="The older prefix folds into dated observations and a long-arc reflection; only the most recent turns stay verbatim."
+{
+  "html": "<div class=\"om\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Reflections</span><small class=\"diagram-muted\">long-arc summary, condensed from the observation log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observations</span><small class=\"diagram-muted\">dense, dated entries folding stretches of raw messages</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Recent raw messages</span><small class=\"diagram-muted\">last N turns, kept <strong>verbatim</strong> — never folded</small></div></div>",
+  "css": ".om{display:flex;flex-direction:column-reverse;align-items:stretch;gap:8px}.om .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.om .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+प्रत्येक मोड़ पर, रीड साइड इन्हें एक स्व-लेबल वाले `[Observational Memory]` ब्लॉक में इकट्ठा करता है जो कच्चे पुराने उपसर्ग को प्रतिस्थापित करता है, हाल ही में कच्ची विंडो को बरकरार रखता है, और मॉडल को कॉम्पैक्ट रिकॉर्ड को आधिकारिक मानने के लिए कहता है (पूरे काम को दोबारा न करें, रिकॉर्ड किए गए निर्णयों, नामों, तिथियों और स्थिति पर भरोसा करें)।
+
+## संघनन कैसे चलता है {#compaction}
+
+दो पास **फायर-एंड-भूल, सर्वोत्तम प्रयास** चरण के बाद एक साफ मोड़ के रूप में चलते हैं, इसलिए वे उपयोगकर्ता-दृश्यमान प्रतिक्रिया में कभी भी विलंबता नहीं जोड़ते हैं और किसी भी विफलता को निगल लिया जाता है:
+
+1. **ऑब्जर्वर** - एक बार जब थ्रेड के _unobserved_ संदेश अवलोकन टोकन सीमा से अधिक हो जाते हैं, तो उन्हें एक सघन अवलोकन प्रविष्टि में बदल देता है।
+2. **परावर्तक** - एक बार जब निरंतर अवलोकन लॉग स्वयं प्रतिबिंब टोकन सीमा से अधिक हो जाता है, तो अवलोकनों को उच्च-स्तरीय प्रतिबिंब में संघनित कर देता है।
+
+```an-diagram title="Two best-effort passes after a clean turn" summary="Each pass no-ops below its threshold, so running the compactor every turn is cheap. Failures are swallowed and never add latency."
+{
+  "html": "<div class=\"om-pass\"><div class=\"diagram-node\">Clean turn ends<br><small class=\"diagram-muted\">fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observer</span><small class=\"diagram-muted\">unobserved tokens &gt; 30k? &rarr; fold into one observation</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Reflector</span><small class=\"diagram-muted\">observation log &gt; 40k? &rarr; condense into a reflection</small></div></div>",
+  "css": ".om-pass{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.om-pass .diagram-node,.om-pass .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.om-pass .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+दोनों अपनी सीमा से नीचे नो-ऑप पास करते हैं, इसलिए प्रत्येक मोड़ के बाद कॉम्पेक्टर को कॉल करना सस्ता है। चूँकि OM अस्थिर कच्चे उपसर्ग को स्थिर संकुचित पाठ से बदल देता है, यह एक लंबे धागे के घुमावों पर **कैश-स्थिर** संकेत भी रखता है।
+
+ओएम डेटा ऐप के अपने SQL डेटाबेस में रहता है, जिसका दायरा मालिक (और मौजूद होने पर संगठन) तक होता है - बाकी फ्रेमवर्क के समान स्कोपिंग मॉडल। इसे कभी भी उपयोगकर्ताओं के बीच साझा नहीं किया जाता है।
+
+## कॉन्फ़िगरेशन {#config}
+
+डिफ़ॉल्ट रूढ़िवादी हैं। एक ऑपरेटर `AGENT_NATIVE_OM_*` पर्यावरण चर के साथ तैनाती के समय कॉम्पैक्शन डायल कर सकता है (ऐप कोड की कोई पुन: तैनाती की आवश्यकता नहीं है); एक अमान्य या अनुपलब्ध मान हमेशा नामित डिफ़ॉल्ट पर वापस आ जाता है।
+
+| पर्यावरण संस्करण                              | डिफ़ॉल्ट | यह क्या नियंत्रित करता है                                                                  |
+| --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
+| `AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD` | `30000`  | अनअवलोकित-संदेश टोकन जो पर्यवेक्षक को उन्हें एक अवलोकन में मोड़ने के लिए प्रेरित करते हैं। |
+| `AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD`  | `40000`  | अवलोकन-लॉग टोकन जो परावर्तक को प्रतिबिंब में संघनित होने के लिए ट्रिगर करते हैं।           |
+| `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`    | `12`     | सबसे हाल के कितने संदेश शब्दशः रहते हैं (कभी भी अवलोकन में तब्दील नहीं होते)।              |
+
+ऑब्जर्वर और रिफ्लेक्टर आउटपुट कैप (4000/2000 टोकन) बजट को उड़ाते हुए एक सिंगल कॉम्पैक्शन पास रखते हैं; वे `resolveObservationalMemoryConfig({ ... })` के माध्यम से कोड में ट्यून करने योग्य हैं लेकिन एनवी-एक्सपोज़्ड नहीं हैं।
+
+> [!TIP]
+> जल्द ही कॉम्पैक्ट करने के लिए थ्रेसहोल्ड कम करें (सस्ते लंबे धागे, थोड़ा अधिक सारांश); संक्षिप्त करने से पहले संदर्भ में अधिक कच्चा इतिहास रखने के लिए उन्हें बढ़ाएं। यदि आपके वर्कफ़्लो को लंबी शब्दशः पूंछ की आवश्यकता है तो `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` को उच्चतर सेट करें।
+
+## जब यह शुरू होता है {#when}
+
+ओएम केवल थ्रेड्स के व्यवहार को इतना लंबे समय तक बदलता है कि कम से कम एक अवलोकन या प्रतिबिंब उत्पन्न हो सके। ठोस रूप से:
+
+- एकदम नया या छोटा धागा: अभी तक कोई ओएम प्रविष्टियाँ नहीं → संदर्भ सादा प्रतिलेख है, अपरिवर्तित।
+- एक लंबा धागा जो अवलोकन सीमा को पार कर गया है: पुराने उपसर्ग को कॉम्पैक्ट `[Observational Memory]` ब्लॉक द्वारा प्रतिस्थापित किया गया है, हाल ही में कच्ची पूंछ शब्दशः रहती है, और टोकन का उपयोग काफी हद तक कम हो जाता है।
+
+इंजेक्शन सबसे अच्छा प्रयास और सीमा-सुरक्षित है - यदि एक सुरक्षित ट्रिम बिंदु नहीं पाया जा सकता है (उदाहरण के लिए एक लंबित टूल-उपयोग/परिणाम जोड़ी विंडो किनारे पर बैठती है), ओएम लंबित टूल परिणाम को छोड़ने के जोखिम के बजाय ट्रिमिंग के बिना मेमोरी ब्लॉक को _additively_ इंजेक्ट करता है।
+
+## संबंधित
+
+- [**Using Your Agent**](/docs/using-your-agent) - आपके ऐप के बगल में डॉक किए गए एजेंट के साथ काम करने का दैनिक लूप।
+- [**Observability**](/docs/observability) - प्रति रन टोकन और लागत मेट्रिक्स, जहां ओएम की बचत दिखाई देती है।
+- [**Custom Agents & Teams**](/docs/agent-teams) - लंबे समय तक चलने वाले उप-एजेंट को समान संघनन से लाभ होता है।