halo-record

# halo-record

छेड़छाड़-स्पष्ट **AI एजेंट्स के लिए ऑडिट ट्रेल्स** — हैश-चेन्ड Runtime Records, जिन्हें एक Runtime Report के रूप में प्रस्तुत किया जाता है जिसे आपके ग्राहक स्वयं जाँच सकते हैं।

आपके instrumentation द्वारा कैप्चर की गई प्रत्येक क्रिया (टूल कॉल्स, मॉडल कॉल्स, डेटा एक्सेस, अनुमोदन) एक **Runtime Record** बन जाती है, जो एक append-only, हैश-चेन्ड लॉग में दर्ज होती है; **Runtime Report** उस चेन को एक HTML पेज के रूप में प्रस्तुत करता है जो पाठक के ब्राउज़र में हैश चेन की पुनर्गणना करता है और जो प्रदर्शित करता है उसे उन रिकॉर्ड्स से रेंडर करता है जिन्हें उसने सत्यापित किया है (ऐसी जाँच के लिए जो पेज के स्वयं के कोड पर निर्भर न हो, JSONL पर `halo verify` चलाएँ)। चेन का चेकपॉइंट रखने वाला कोई भी पक्ष यह सत्यापित कर सकता है कि उस चेकपॉइंट तक के रिकॉर्ड्स उसके लिए गए होने के बाद से बदले नहीं गए हैं, बिना उनके निर्माता पर भरोसा किए — वह चेकपॉइंट ही भार वहन करने वाला हिस्सा है: चेन अकेले ही रिकॉर्डर चलाने वाले पक्ष को छोड़कर सभी के विरुद्ध छेड़छाड़-स्पष्ट है ([LIMITS.md §1](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md))। जब किसी ग्राहक की सुरक्षा टीम पूछे "आपके एजेंट ने हमारे डेटा के साथ क्या किया?", तो आप उन्हें एक पैराग्राफ के बजाय एक लिंक थमा देते हैं। सुरक्षा समीक्षाएँ पहले से ही SOC 2 चेकलिस्ट के साथ-साथ AI से जुड़े प्रश्न पूछती हैं — और तेजी से ये प्रश्न ISO 42001, EU AI Act के रिकॉर्ड-कीपिंग अनुच्छेदों, और ग्राहकों की अपनी प्रश्नावलियों से आ रहे हैं। आज एक लिखित आश्वासन अभी भी पास हो जाता है। इस परियोजना के पीछे का दाँव यह है कि यह ज्यादा दिन नहीं चलेगा।

**[Help Net Security](https://www.helpnetsecurity.com/2026/08/31/halo-record-open-source-ai-agent-audit-trail/)** में प्रमुखता से शामिल (अगस्त 2026)।

रिकॉर्ड प्रारूप खुला है और इसे लागू करना निःशुल्क है। यह पैकेज संदर्भ कार्यान्वयन है: रिकॉर्डर, सत्यापनकर्ता, विटनेस क्लाइंट, और रिपोर्ट सर्वर।

> **halo-record का उपयोग कर रहे हैं, या इसके बारे में सोच रहे हैं?** मुझे बताएँ कि आप कौन हैं और किसलिए → [halo-record का उपयोग कौन कर रहा है?](https://github.com/bkuan001/halo-record/discussions/7)

## स्वयं जाँचें

आपसे कहा जा रहा है कि आप अपने एजेंट के अंदर एक रिकॉर्डर लगाएँ। आपको इसे विश्वास पर नहीं लेना चाहिए:

- **शून्य रनटाइम निर्भरताएँ।** केवल मानक लाइब्रेरी। `pip install halo-record` ठीक एक पैकेज इंस्टॉल करता है।
- **कोई नेटवर्क कॉल नहीं**, सिवाय चार ऑप्ट-इन वालों के — एक विटनेस पर एंकरिंग (subject id, एक रिकॉर्ड गणना, और दो चेन फिंगरप्रिंट भेजता है — head और chain root), किसी विटनेस के चेकपॉइंट्स को वापस पढ़ना (subject id भेजता है), RFC 3161 टाइमस्टैम्प (किसी चेकपॉइंट का state hash केवल एक Timestamp Authority को भेजता है), और `halo serve --verify-email` (एक वन-टाइम कोड और रिपोर्ट का subject name, `$HALO_SMTP_HOST` में आपके द्वारा कॉन्फ़िगर किए गए सर्वर के माध्यम से SMTP द्वारा, उस पते पर भेजता है जो रिपोर्ट दर्शक दर्ज करता है)। जब तक आप उन्हें आमंत्रित नहीं करते, ये सभी बंद रहते हैं; कोई अन्य रिकॉर्ड सामग्री आपके इंफ्रास्ट्रक्चर से बाहर नहीं जाती।
- **कच्चे टूल आर्गुमेंट्स हैश किए जाते हैं, साथ में एक रिडैक्टेड सारांश होता है।** आर्गुमेंट्स एक कैनोनिकल हैश और एक सारांश के रूप में संग्रहीत होते हैं: आर्गुमेंट टेक्स्ट जिसमें ज्ञात सीक्रेट और PII पैटर्न मास्क किए गए हों, 200 अक्षरों तक सीमित। कोई भी पैटर्न से मेल न खाने वाला छोटा इनपुट सारांश में पूर्ण रूप से दिखाई देता है; hash-only मोड (`summaries=False`) कोई सारांश नहीं रखता। रिडैक्शन सर्वोत्तम-प्रयास है (सामान्य सीक्रेट और PII प्रारूपों पर regex के साथ-साथ एक एन्ट्रॉपी कैच-ऑल): इसे defense-in-depth मानें, गारंटी नहीं। `summary` से परे आपके द्वारा दिए गए outcome फ़ील्ड्स को उन्हीं पैटर्नों से स्कैन और मास्क किया जाता है, लेकिन 200 अक्षरों तक नहीं काटा जाता (LIMITS §13)।
- **ऑडिट करने लायक छोटा।** ~8,700 पंक्तियाँ Python, जिसमें रिपोर्ट पेज की एम्बेडेड JavaScript और CSS भी शामिल है (कोड पंक्तियाँ, रिक्त पंक्तियों, टिप्पणियों, और docstrings को छोड़कर)। इसे एक दिन में पूरा पढ़ें।
- **Apache-2.0।**
- **कागज़ी कार्रवाई प्रथम श्रेणी की है।** [LIMITS.md](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md) (चेन क्या सिद्ध नहीं कर सकती), [PRIVACY.md](https://github.com/bkuan001/halo-record/blob/main/PRIVACY.md) (रिकॉर्ड्स में क्या होता है और आपकी मशीन से क्या बाहर जाता है), [RETENTION.md](https://github.com/bkuan001/halo-record/blob/main/RETENTION.md) (एक retention नीति के अंतर्गत संचालन), और [REVIEWERS.md](https://github.com/bkuan001/halo-record/blob/main/REVIEWERS.md) — चार-कमांड स्वतंत्र जाँच के साथ-साथ समीक्षा निष्कर्षों के लिए एक उद्धरण प्रारूप।

प्रत्येक परत क्या सिद्ध करती है — इस परियोजना में भार वहन करने वाला अंतर ([LIMITS.md §1](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md)): आपके पास स्वयं की चेन सिद्ध करती है कि रिकॉर्ड्स **संपादित** नहीं किए गए, उस head के सापेक्ष जो किसी और के पास पहले से है; केवल ऑपरेटर के बाहर रखे गए चेकपॉइंट्स सिद्ध करते हैं कि कोई **हटाया** नहीं गया; और कोई भी हैश यह सिद्ध नहीं करता कि प्रत्येक क्रिया **कैप्चर** की गई थी।

| दावा | स्व-धारित चेन | + बाहरी चेकपॉइंट्स | + विश्वसनीय कैप्चर |
|---|---|---|---|
| स्थापित आर्टिफैक्ट में संपादन का पता लगाना | ✔ | ✔ | ✔ |
| कमिटेड इतिहास के पुनर्लेखन का पता लगाना | — | ✔ | ✔ |
| गुम/देर से आए चेकपॉइंट्स का पता लगाना | — | ✔ (सहमत कैडेंस) | ✔ |
| सिद्ध करना कि प्रत्येक क्रिया रिकॉर्ड की गई थी | — | — | कैप्चर सीमा पर निर्भर |

**इंस्टॉल करने से पहले एक देखें:** [एक नमूना Runtime Report](https://bkuan001.github.io/halo-record/sample-report.html) — काल्पनिक डेटा, वास्तविक चेन, और इसे खोलने पर इसकी स्क्रिप्ट आपके ब्राउज़र में एम्बेडेड रिकॉर्ड्स की हैश चेन की पुनर्गणना करती है।

## 60-सेकंड डेमो

किसी एजेंट की आवश्यकता नहीं। [uv](https://docs.astral.sh/uv/) के साथ, कुछ भी इंस्टॉल करने की जरूरत नहीं:

```
uvx --from halo-record halo demo --serve
```

या क्लासिक तरीका:

```
pip install halo-record
halo demo --serve
```

या तो दो ग्राहकों वाले एक काल्पनिक सपोर्ट-एजेंट विक्रेता को स्कैफ़ोल्ड करता है, श्रृंखलाओं को साक्षी बनाता है (ऑपरेटर के बाहर वाले के लिए एक स्थानीय साक्षी फ़ाइल को प्रतिस्थापित करता है — देखें [LIMITS.md §1](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md)), उनकी गेटेड Runtime Reports प्रस्तुत करता है, और आपके ब्राउज़र में ऑपरेटर कंसोल खोलता है। फिर टैम्पर परीक्षण आज़माएँ: `.jsonl` फ़ाइलों में से एक से एक पंक्ति हटाएँ और पुनः लोड करें। रिपोर्ट इसे पकड़ लेती है।

## अपने स्वयं के एजेंट को रिकॉर्ड करें

सीमा पर एक पंक्ति:

```python
from halo_record import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # wraps your entrypoint; records the run boundary to ./audit.jsonl — add record_call() or a framework adapter at each tool boundary to capture individual calls
```

`from halo import ...` सुविधा शिम भी शिप होती है — लेकिन PyPI पर `halo` नाम एक असंबंधित terminal-spinner पैकेज का है, और यदि वह पैकेज इंस्टॉल है तो इम्पोर्ट में वही जीतता है। `halo_record` स्पष्ट है, इसलिए उदाहरण इसे उपयोग करते हैं।

`log=` के बिना, रिकॉर्ड `~/.halo/my-agent.jsonl` में जाते हैं (प्रति एजेंट एक चेन)। रैपर रन सीमा को सील करता है; साक्ष्य प्रति-कॉल रिकॉर्ड में रहता है। उन्हें एक फ्रेमवर्क एडाप्टर (नीचे मैट्रिक्स) से कैप्चर करें — या स्पष्ट रूप से, जो यह भी दिखाता है कि प्रतिनिधिमंडल कैसे लिंक होता है:

```python
from halo_record import Recorder, record_call

rec = Recorder("audit.jsonl")

with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call:            # one sealed record per tool call
    call.result = crm.lookup("acct-9")

with record_call(rec, "payments.refund", {"amount": 120},
                 parent_id=rec.last_record_id()) as call:                      # child links to the action that spawned it
    call.result = payments.refund(120)
```

फिर रिपोर्ट रेंडर करें:

```
halo report audit.jsonl -o report.html    # one chain -> HTML that re-verifies in the browser
halo serve ./records --port 8721          # all tenants, gated per customer
```

0.2.45 द्वारा पहली बार सर्व किए गए डायरेक्टरी को अपग्रेड करना? `halo serve` स्टार्टअप पर प्रत्येक पूर्व अनुदान को फिर से पढ़ता है। किसी फ़ाइल पर अनुदान जिसके रिकॉर्ड में कोई विषय आईडी नहीं है (एक सादा `Recorder` फ़ाइल जैसे `agent.jsonl`) को क्वारंटीन कर दिया जाता है और प्रत्येक स्टार्टअप पर `halo grant` कमांड के साथ प्रिंट किया जाता है जो इसे फिर से जारी करता है — देखें [LIMITS.md §17, "Serving a directory first served by 0.2.45"](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#17-one-chain-file-per-subject)।

क्विकस्टार्ट तब समाप्त होता है जब आप ब्राउज़र में अपने स्वयं के एजेंट की Runtime Report देख रहे हों। यदि आपको एक JSONL फ़ाइल मिली और कोई रिपोर्ट नहीं, तो कुछ गलत है: एक इश्यू खोलें।

### सत्यापन ब्लॉक

यदि किसी गार्डरेल या नीति परत ने कार्रवाई की जाँच की, तो उसका निर्णय रिकॉर्ड पर सवार हो सकता है — एक वैकल्पिक ब्लॉक जो रिकॉर्ड करता है कि गेट ने क्या निर्णय लिया, हर अन्य फ़ील्ड की तरह हैश चेन में सील कर दिया गया:

```python
from halo_record import build

build("tool_call", "security", tool="payments.refund",
      verification={"status": "allowed", "verifier": "gate/1.2",
                    "policy_ref": "sha256:1f3a...",
                    "checked_at": "2026-08-01T12:00:00Z"})
```

एक नामकरण नोट: पैकेज एक `record` *फ़ंक्शन* (डेकोरेटर) निर्यात करता है, जो पैकेज ऑब्जेक्ट पर `halo_record.record` *मॉड्यूल* को छाया देता है। जब आप इसके आंतरिक भाग चाहते हैं तो सीधे मॉड्यूल पथ से आयात करें — `from halo_record.record import build` — न कि `import halo_record.record as record`।

जो रिकॉर्ड में इस प्रकार सील हो जाता है:

```json
"verification": {"status": "allowed", "verifier": "gate/1.2", "policy_ref": "sha256:1f3a...", "checked_at": "2026-08-01T12:00:00Z"}
```

`record_call(...)` वही `verification=` कीवर्ड स्वीकार करता है। ब्लॉक के भीतर `status` आवश्यक है; `verifier`, `policy_ref`, और `checked_at` वैकल्पिक हैं। प्रत्येक स्टेटस का क्या अर्थ है:

| स्टेटस | गेट क्या रिपोर्ट करता है | क्या कार्रवाई निष्पादित हुई? |
|---|---|---|
| `allowed` | इसने कार्रवाई की अनुमति दी | हाँ — कार्रवाई आगे बढ़ी |
| `blocked` | इसने कार्रवाई से इनकार किया | यह इंटीग्रेशन द्वारा निर्धारित होता है, इस फ़ील्ड द्वारा नहीं — एक रिकॉर्ड अभी भी एक परिणाम वहन कर सकता है, और एक ब्लॉक अपने आप में गैर-निष्पादन साबित नहीं करता |
| `modified` | इसने निष्पादन से पहले कार्रवाई को बदल दिया — `action.input` कार्रवाई का वर्णन **निष्पादित रूप में**, संशोधन के बाद करता है | हाँ, बदले हुए रूप में |
| `unverified` | यह चला (या इससे परामर्श लिया गया) लेकिन कोई निर्धारण नहीं किया — यह अनुपस्थित ब्लॉक से भिन्न है, जिसका अर्थ है कि कोई सत्यापन दावा बिल्कुल नहीं किया गया | हाँ — कार्रवाई बिना किसी निर्णय के आगे बढ़ी |

यह ब्लॉक ऑपरेटर के इंटीग्रेशन कोड द्वारा प्रदान किया जाता है और रिकॉर्ड करता है कि यह क्या रिपोर्ट करता है कि गेट ने कहा — वही विश्वास मुद्रा जो `principal` की है (देखें [LIMITS](https://github.com/bkuan001/halo-record/blob/main/LIMITS.md#11-verification-status-is-the-gates-report-not-halos-finding))। सीलिंग साबित करती है कि स्टेटस को बाद में संपादित नहीं किया गया; यह साबित नहीं करती कि जाँच हुई, कि निर्णय सही था, या कि एक अवरुद्ध कार्रवाई निष्पादित नहीं हुई। यह स्वतंत्र सत्यापन नहीं है।

`policy_ref` को साक्ष्य के रूप में उपयोग करने योग्य बनाने के लिए, नियमसेट का एक कंटेंट हैश उपयोग करें और नियमसेट आर्टिफैक्ट को बनाए रखें — एक अनसुलझा लेबल फ़ील्ड को सजावटी बना देता है।

## जो आप पहले से चलाते हैं उससे जुड़ें

| सीमा पर कैप्चर किया गया | मौजूदा टेलीमेट्री से इनजेस्ट किया गया |
|---|---|
| नेटिव रिकॉर्डर (`from halo_record import trace`) | OpenTelemetry GenAI स्पैन |
| MCP इंटरसेप्टर | LiteLLM कॉलबैक |
| LangChain / LangGraph कॉलबैक | Langfuse एक्सपोर्ट |
| OpenAI Agents SDK हुक | कोई भी गेटवे / रिवर्स-प्रॉक्सी लॉग |
| Claude Agent SDK हुक | Claude Code और Codex CLI `PostToolUse` हुक (टूल चलने के बाद फायर होते हैं) |

फ्रेमवर्क एडाप्टर और इनजेशन पथ प्रत्येक रिकॉर्ड को एक `source` टैग के साथ स्टैम्प करते हैं, इसलिए रिपोर्ट बताती है कि साक्ष्य का प्रत्येक टुकड़ा कैसे एकत्र किया गया था। कैप्चर किए गए और इनजेस्ट किए गए रिकॉर्ड एक ही चेन में रहते हैं।

LangChain / LangGraph के लिए, यह एक कॉलबैक हैंडलर है:

```python
from halo_record import Recorder
from halo_record.integrations.langchain import HaloCallbackHandler

recorder = Recorder("audit.jsonl")
result = my_chain.invoke(inputs, config={"callbacks": [HaloCallbackHandler(recorder)]})   # every tool call becomes a record
```

MCP के लिए, एक कॉल क्लाइंट सत्र को रैप करती है — और फिर *कोई भी* MCP-उपयोग करने वाला एजेंट हर टूल कॉल के लिए रिकॉर्ड उत्सर्जित करता है, चाहे उसे कोई भी फ्रेमवर्क चलाए:

```python
from mcp import Client   # mcp 2.x
from halo_record import Recorder
from halo_record.integrations.mcp import instrument_client_session

async def run(server):   # an MCPServer, a server URL, or stdio parameters
    async with Client(server) as client:
        instrument_client_session(client, Recorder("audit.jsonl"), server="stripe")
        await client.call_tool("charge", {"customer": "cus_123", "amount": 500})   # recorded
```

Wrapped क्लाइंट पर प्रत्येक `call_tool()` रिकॉर्ड किया जाता है, और एक त्रुटि परिणाम लौटाने वाला टूल `error` के रूप में सील कर दिया जाता है (अडैप्टर दोनों `isError` और mcp 2.x `is_error` को पढ़ता है)। mcp 1.x पर, `Client` के बजाय initialized `ClientSession` पास करें; wrapper वही रहता है।

गेटवे या प्रॉक्सी लॉग्स के लिए (Cloudflare AI Gateway, Portkey, मॉडल के सामने nginx), एक लॉग पंक्ति को चेन में मैप करें — स्पष्ट रूप से ingested के रूप में टैग किया गया, boundary-captured नहीं:

```python
from halo_record.integrations.gateway import record_log

record_log(Recorder("audit.jsonl"), {"tool": "gen_ai:gpt-4o", "model": "gpt-4o", "status": 200, "subject": "acme-corp"})
```

OpenTelemetry GenAI spans उत्सर्जित करने वाला कोई भी सिस्टम (CrewAI, LlamaIndex, और OTel instrumentation वाले अधिकांश agent frameworks) OTel adapter के माध्यम से chain में शामिल हो जाता है, और [TypeScript package](https://github.com/bkuan001/halo-record-ts) Vercel AI SDK और JS agent ecosystem के लिए native adapters प्रदान करता है। अपने stack के लिए adapter नहीं मिल रहा? एक issue खोलें। अधिकांश adapters लगभग सौ lines के होते हैं।

## अपने coding agent को record करें (Claude Code या Codex)

Claude Code हर tool call के बाद एक `PostToolUse` hook fire करता है। इसे `halo hook` पर point करें और हर action — file writes, shell commands, MCP connector calls — local chain में एक record बन जाता है। कोई code changes नहीं; एक settings entry:

```json
{
  "hooks": {
    "PostToolUse": [
      {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}
```

इसे `~/.claude/settings.json` में जोड़ें और रिकॉर्ड `~/.halo/audit.jsonl` में दर्ज हो जाते हैं (`$HALO_LOG` से ओवरराइड करें)। जो शुद्ध-ऑर्केस्ट्रेशन टूल्स किसी डेटा, नेटवर्क, या बाहरी स्थिति को नहीं छूते, उन्हें छोड़ दिया जाता है — चेन विश्वास-सीमा क्रियाओं को रिकॉर्ड करती है, सोच को नहीं। सारांश के बिना सामग्री हैश रिकॉर्ड करने के लिए `HALO_HASH_ONLY=1` सेट करें। प्रत्येक रिकॉर्ड को उस एजेंट बिल्ड से बाँधने के लिए `HALO_AGENT_VERSION` (और वैकल्पिक रूप से `HALO_AGENT_MODEL`) सेट करें जिसने इसे उत्पन्न किया — जब कोई ऑडिटर किसी दिए गए विंडो में चल रहे संस्करण के बारे में पूछता है, तो एक्सपोर्ट स्मृति के बजाय कॉलम द्वारा उत्तर देता है।

Codex CLI समान इवेंट शेप के साथ समान लाइफसाइकल हुक्स प्रदान करता है (हुक्स डिफ़ॉल्ट रूप से चालू हैं)। इसे `~/.codex/hooks.json` में जोड़ें और Codex के शेल कमांड, `apply_patch` एडिट्स, और MCP कॉल्स उसी चेन में दर्ज हो जाते हैं:

```json
{
  "hooks": {
    "PostToolUse": [
      {"matcher": ".*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}
```

The hook दोनों को event से अलग करता है (Codex `turn_id` और `model` जोड़ता है) और प्रत्येक record को `claude-code` या `codex` लेबल करता है; किसी एक को बाध्य करने के लिए `HALO_HOOK_AGENT` सेट करें। दोनों ingested tier हैं: एक `PostToolUse` hook tool चलने के बाद fire होता है, इसलिए record उसी से बनाया जाता है जो harness रिपोर्ट करता है।

यदि आपको रिपोर्ट से यह उत्तर चाहिए कि "यह run किन rules के अंतर्गत हुआ?", तो session के लिए effective authority के JSON snapshot पर `HALO_AUTHORITY_FILE` सेट करें। इसे privacy-safe रखें: hashes और refs, raw prompts, private policy text, secrets, या पूर्ण tool schemas नहीं — ज्ञात secret और personal-data formats seal time पर mask किए जाते हैं, लेकिन hashes और refs बिना छेड़े पास हो जाते हैं और free-form text detect नहीं होता (देखें LIMITS §6)। `snapshot_id` का पुनः उपयोग तभी करें जब underlying authority अपरिवर्तित हो; समान id और अपरिवर्तित content वाले क्रमागत records compact किए जाते हैं — बदले हुए content पर पुनः उपयोग किया गया id पूर्ण रूप में संग्रहीत होता है, एक notice के साथ।

```json
{
  "snapshot_id": "auth_2026_07_08T1100Z",
  "captured_at": "2026-07-08T11:00:00Z",
  "scope": "session",
  "workspace": {"path_hash": "sha256:...", "git_commit": "abc1234"},
  "refs": [
    {"kind": "project_rules", "id": "CLAUDE.md", "hash": "sha256:...", "loaded": true, "truncated": false},
    {"kind": "mcp_tool_registry", "id": "filesystem", "hash": "sha256:..."}
  ],
  "omissions": [{"kind": "private_policy", "reason": "customer_secret", "hash": "sha256:..."}],
  "stale_if": ["project_rules_hash_changed", "mcp_tool_registry_hash_changed"]
}
```

```sh
HALO_AUTHORITY_FILE=./authority.json halo hook
```

---

[Read more](https://github.com/bkuan001/halo-record)