1#!/usr/bin/env python3
2"""
3Evidence Store — append-only evidence persistence for deep-research v3.0.
4 
5CLI subcommands:
6  init         Create empty evidence.jsonl in a run directory
7  add          Append an evidence row, return evidence_id
8  list         List evidence rows, optionally filtered by source_id
9  export       Export evidence as JSON array
10 
11Evidence identity:
12  evidence_id = sha256(source_id + normalized_quote + locator)[:16]
13 
14All state is append-only JSONL. Evidence is never modified after capture.
15"""
16 
17import argparse
18import hashlib
19import json
20import os
21import re
22import sys
23from datetime import datetime, timezone
24 
25 
26# ---------------------------------------------------------------------------
27# Evidence ID computation
28# ---------------------------------------------------------------------------
29 
30_WHITESPACE_RE = re.compile(r'\s+')
31 
32 
33def normalize_quote(quote: str) -> str:
34    """Normalize whitespace for stable hashing."""
35    return _WHITESPACE_RE.sub(' ', quote.strip()).lower()
36 
37 
38def compute_evidence_id(source_id: str, quote: str, locator: str | None) -> str:
39    """sha256(source_id + normalized_quote + locator)[:16] hex."""
40    payload = source_id + normalize_quote(quote) + (locator or '')
41    return hashlib.sha256(payload.encode('utf-8')).hexdigest()[:16]
42 
43 
44# ---------------------------------------------------------------------------
45# JSONL helpers (shared pattern with citation_manager)
46# ---------------------------------------------------------------------------
47 
48def append_jsonl(path: str, obj: dict) -> None:
49    with open(path, 'a') as f:
50        f.write(json.dumps(obj, ensure_ascii=False) + '\n')
51 
52 
53def read_jsonl(path: str) -> list[dict]:
54    rows = []
55    if not os.path.exists(path):
56        return rows
57    with open(path) as f:
58        for line in f:
59            line = line.strip()
60            if line:
61                rows.append(json.loads(line))
62    return rows
63 
64 
65# ---------------------------------------------------------------------------
66# Subcommands
67# ---------------------------------------------------------------------------
68 
69def cmd_init(args: argparse.Namespace) -> None:
70    """Create empty evidence.jsonl if it doesn't exist."""
71    out_dir = os.path.abspath(args.dir)
72    path = os.path.join(out_dir, 'evidence.jsonl')
73    if not os.path.exists(path):
74        os.makedirs(out_dir, exist_ok=True)
75        open(path, 'w').close()
76    print(json.dumps({'status': 'ok', 'path': path}))
77 
78 
79def cmd_add(args: argparse.Namespace) -> None:
80    """Append evidence row, print evidence_id."""
81    data = json.loads(args.json)
82    source_id = data.get('source_id', '')
83    quote = data.get('quote', '')
84    if not source_id or not quote:
85        print(json.dumps({'error': 'source_id and quote are required'}), file=sys.stderr)
86        sys.exit(1)
87 
88    locator = data.get('locator')
89    evidence_id = compute_evidence_id(source_id, quote, locator)
90    evidence_path = os.path.join(args.dir, 'evidence.jsonl')
91 
92    # Check for duplicate
93    existing = read_jsonl(evidence_path)
94    for row in existing:
95        if row.get('evidence_id') == evidence_id:
96            print(json.dumps({
97                'status': 'duplicate',
98                'evidence_id': evidence_id,
99            }))
100            return
101 
102    valid_types = {'direct_quote', 'paraphrase', 'data_point', 'figure_reference', 'methodology'}
103    evidence_type = data.get('evidence_type', 'direct_quote')
104    if evidence_type not in valid_types:
105        evidence_type = 'direct_quote'
106 
107    row = {
108        'evidence_id': evidence_id,
109        'source_id': source_id,
110        'retrieval_query': data.get('retrieval_query'),
111        'locator': locator,
112        'quote': quote,
113        'evidence_type': evidence_type,
114        'captured_at': datetime.now(timezone.utc).isoformat(),
115    }
116    append_jsonl(evidence_path, row)
117    print(json.dumps({
118        'status': 'added',
119        'evidence_id': evidence_id,
120        'source_id': source_id,
121    }))
122 
123 
124def cmd_list(args: argparse.Namespace) -> None:
125    """List evidence rows, optionally filtered."""
126    evidence_path = os.path.join(args.dir, 'evidence.jsonl')
127    rows = read_jsonl(evidence_path)
128 
129    if args.source_id:
130        rows = [r for r in rows if r.get('source_id') == args.source_id]
131 
132    # Deduplicate by evidence_id
133    seen = set()
134    unique = []
135    for r in rows:
136        eid = r.get('evidence_id')
137        if eid not in seen:
138            seen.add(eid)
139            unique.append(r)
140 
141    print(json.dumps({
142        'count': len(unique),
143        'evidence': unique,
144    }, indent=2, ensure_ascii=False))
145 
146 
147def cmd_export(args: argparse.Namespace) -> None:
148    """Export all evidence as JSON array."""
149    evidence_path = os.path.join(args.dir, 'evidence.jsonl')
150    rows = read_jsonl(evidence_path)
151 
152    # Deduplicate
153    seen = set()
154    unique = []
155    for r in rows:
156        eid = r.get('evidence_id')
157        if eid not in seen:
158            seen.add(eid)
159            unique.append(r)
160 
161    print(json.dumps(unique, indent=2, ensure_ascii=False))
162 
163 
164# ---------------------------------------------------------------------------
165# CLI entry point
166# ---------------------------------------------------------------------------
167 
168def main() -> None:
169    parser = argparse.ArgumentParser(
170        prog='evidence_store',
171        description='Append-only evidence persistence for deep-research v3.0',
172    )
173    sub = parser.add_subparsers(dest='command', required=True)
174 
175    # init
176    p_init = sub.add_parser('init', help='Create empty evidence.jsonl')
177    p_init.add_argument('--dir', required=True, help='Run directory')
178 
179    # add
180    p_add = sub.add_parser('add', help='Append evidence row')
181    p_add.add_argument('--json', required=True, help='JSON with source_id, quote, locator, evidence_type, retrieval_query')
182    p_add.add_argument('--dir', required=True, help='Run directory containing evidence.jsonl')
183 
184    # list
185    p_list = sub.add_parser('list', help='List evidence rows')
186    p_list.add_argument('--dir', required=True, help='Run directory')
187    p_list.add_argument('--source-id', default=None, help='Filter by source_id')
188 
189    # export
190    p_export = sub.add_parser('export', help='Export all evidence as JSON array')
191    p_export.add_argument('--dir', required=True, help='Run directory')
192 
193    args = parser.parse_args()
194 
195    dispatch = {
196        'init': cmd_init,
197        'add': cmd_add,
198        'list': cmd_list,
199        'export': cmd_export,
200    }
201    dispatch[args.command](args)
202 
203 
204if __name__ == '__main__':
205    main()
206