nlp-refinement-cli 0.9.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. nlp_refinement/__init__.py +1 -0
  2. nlp_refinement/diagnostic_doe_support.py +84 -0
  3. nlp_refinement/doe_receipt_retention.py +81 -0
  4. nlp_refinement/format_contracts.py +157 -0
  5. nlp_refinement/host_client.py +505 -0
  6. nlp_refinement/host_diagnostics.py +430 -0
  7. nlp_refinement/host_execution_request.py +15 -0
  8. nlp_refinement/host_executor.py +104 -0
  9. nlp_refinement/host_refine.py +82 -0
  10. nlp_refinement/m8_doe_fixtures.py +28 -0
  11. nlp_refinement/m8_review_coordinator.py +370 -0
  12. nlp_refinement/patch_proposal_adapter.py +303 -0
  13. nlp_refinement/refine.py +372 -0
  14. nlp_refinement/repair_feasibility.py +327 -0
  15. nlp_refinement/resources/__init__.py +0 -0
  16. nlp_refinement/resources/prompts/patch-proposal-phase.v5.md +51 -0
  17. nlp_refinement/resources/prompts/review-phase.v5.md +57 -0
  18. nlp_refinement/resources/schemas/v5/acceptance-trace.schema.json +17 -0
  19. nlp_refinement/resources/schemas/v5/artifact.schema.json +17 -0
  20. nlp_refinement/resources/schemas/v5/finding.schema.json +27 -0
  21. nlp_refinement/resources/schemas/v5/patch-proposal-result.schema.json +66 -0
  22. nlp_refinement/resources/schemas/v5/phase-envelope.schema.json +18 -0
  23. nlp_refinement/resources/schemas/v5/retention-policy.schema.json +16 -0
  24. nlp_refinement/resources/schemas/v5/review-result.schema.json +37 -0
  25. nlp_refinement/resources/schemas/v5/run.schema.json +22 -0
  26. nlp_refinement/review_adapter.py +203 -0
  27. nlp_refinement/sensitive_data.py +98 -0
  28. nlp_refinement/state_store.py +1025 -0
  29. nlp_refinement_cli-0.9.0.dist-info/METADATA +300 -0
  30. nlp_refinement_cli-0.9.0.dist-info/RECORD +35 -0
  31. nlp_refinement_cli-0.9.0.dist-info/WHEEL +5 -0
  32. nlp_refinement_cli-0.9.0.dist-info/entry_points.txt +4 -0
  33. nlp_refinement_cli-0.9.0.dist-info/licenses/LICENSE +201 -0
  34. nlp_refinement_cli-0.9.0.dist-info/licenses/NOTICE +4 -0
  35. nlp_refinement_cli-0.9.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,372 @@
1
+ """M2 command adapter for durable-local, review-only refinement runs.
2
+
3
+ This module is deliberately not an MCP server or a Codex command-registration
4
+ mechanism. It supplies a testable local command that a later host adapter may
5
+ call after capability verification.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import hashlib
12
+ import json
13
+ import os
14
+ import secrets
15
+ import sys
16
+ import time
17
+ from pathlib import Path
18
+ from typing import Any
19
+
20
+ from nlp_refinement.patch_proposal_adapter import ingest_patch_proposal, load_patch_proposal
21
+ from nlp_refinement.host_execution_request import HostExecutionRequest
22
+ from nlp_refinement.review_adapter import ingest_review, load_review_result
23
+ from nlp_refinement.sensitive_data import likely_secret_kind
24
+ from nlp_refinement.state_store import FINAL_STATES, StateStore, StateStoreError
25
+
26
+
27
+ # Project identity is independent of the persisted protocol version. Keep it
28
+ # stable while the project-key algorithm itself is unchanged.
29
+ PROJECT_KEY_DOMAIN = "nlp-refinement/project-key/v4\\0"
30
+
31
+
32
+ def default_state_root() -> Path:
33
+ configured = os.environ.get("NLP_REFINEMENT_STATE_ROOT")
34
+ return Path(configured).expanduser() if configured else Path("~/.codex/refinement-loop").expanduser()
35
+
36
+
37
+ def project_identity(project_dir: Path, explicit_project_id: str | None) -> tuple[str, str]:
38
+ """Return a stable-enough local identity and its disclosure-safe mode.
39
+
40
+ The path mode intentionally changes if a non-Git project is moved. A caller
41
+ may use a user-managed project ID to preserve identity across that move.
42
+ """
43
+ if explicit_project_id:
44
+ return f"id:{explicit_project_id}", "explicit-id"
45
+ return f"path:{project_dir.resolve(strict=True)}", "resolved-path"
46
+
47
+
48
+ def project_key(identity: str) -> str:
49
+ return hashlib.sha256(f"{PROJECT_KEY_DOMAIN}{identity}".encode("utf-8")).hexdigest()
50
+
51
+
52
+ def snapshot_hash(value: str) -> str:
53
+ if len(value) != 64 or any(char not in "0123456789abcdef" for char in value):
54
+ raise ValueError("snapshot hash must be a lowercase SHA-256 hex string")
55
+ return value
56
+
57
+
58
+ def now_epoch() -> int:
59
+ return int(time.time())
60
+
61
+
62
+ def output(value: dict[str, Any]) -> None:
63
+ print(json.dumps(value, sort_keys=True, ensure_ascii=False))
64
+
65
+
66
+ def build_parser() -> argparse.ArgumentParser:
67
+ parser = argparse.ArgumentParser(prog="nlp-refinement")
68
+ parser.add_argument("--state-root", type=Path, default=default_state_root())
69
+ subcommands = parser.add_subparsers(dest="command", required=True)
70
+
71
+ start = subcommands.add_parser("start", help="create a review-only run")
72
+ start.add_argument("--project-dir", type=Path, required=True)
73
+ start.add_argument("--redacted-brief-file", type=Path, required=True)
74
+ start.add_argument("--snapshot-hash", required=True)
75
+ start.add_argument("--project-id", help="stable user-managed identity for a moved project")
76
+
77
+ status = subcommands.add_parser("status", help="read a run without changing it")
78
+ status.add_argument("--run-id", required=True)
79
+
80
+ resume = subcommands.add_parser("resume", help="reopen a run only to check its snapshot")
81
+ resume.add_argument("--run-id", required=True)
82
+ resume.add_argument("--observed-snapshot-hash", required=True)
83
+ resume.add_argument(
84
+ "--retry-blocked",
85
+ action="store_true",
86
+ help="explicitly return a BLOCKED run to READY after its snapshot check",
87
+ )
88
+
89
+ review = subcommands.add_parser("review", help="ingest an external structured review result")
90
+ review.add_argument("--run-id", required=True)
91
+ review.add_argument("--review-result-file", type=Path, required=True)
92
+ review.add_argument("--observed-snapshot-hash", required=True)
93
+ review.add_argument(
94
+ "--redaction-status",
95
+ choices=("caller-attested-redacted",),
96
+ required=True,
97
+ help="caller attests that this content is already redacted; this is not an automatic safety proof",
98
+ )
99
+
100
+ proposal = subcommands.add_parser("patch-proposal", help="record a human-only patch proposal without applying it")
101
+ proposal.add_argument("--run-id", required=True)
102
+ proposal.add_argument("--patch-proposal-file", type=Path, required=True)
103
+ proposal.add_argument("--observed-snapshot-hash", required=True)
104
+ proposal.add_argument(
105
+ "--redaction-status",
106
+ choices=("caller-attested-redacted",),
107
+ required=True,
108
+ help="caller attests that this content is already redacted; this is not an automatic safety proof",
109
+ )
110
+ host_request = subcommands.add_parser(
111
+ "host-execution-request",
112
+ help="prepare a no-model request for the external host executor",
113
+ )
114
+ host_request.add_argument("--run-id", required=True)
115
+ host_request.add_argument("--artifact-file", type=Path, required=True)
116
+ host_request.add_argument("--observed-snapshot-hash", required=True)
117
+ retention_preview = subcommands.add_parser("retention-preview", help="show a content-free retention plan without changing the ledger")
118
+ retention_preview.add_argument("--now", type=int, help=argparse.SUPPRESS)
119
+ retention_sweep = subcommands.add_parser("retention-sweep", help="apply one exact, previously previewed retention plan")
120
+ retention_sweep.add_argument("--confirm-plan-hash", required=True)
121
+ retention_sweep.add_argument("--now", type=int, help=argparse.SUPPRESS)
122
+ return parser
123
+
124
+
125
+ def public_status(run: dict[str, Any], event_count: int) -> dict[str, Any]:
126
+ """Never expose the immutable anchor because it carries the redacted brief."""
127
+ return {
128
+ "run_id": run["run_id"],
129
+ "project_key": run["project_key"],
130
+ "state": run["state"],
131
+ "outcome": run["outcome"],
132
+ "revision": run["revision"],
133
+ "target_snapshot_hash": run["target_snapshot_hash"],
134
+ "current_snapshot_hash": run["current_snapshot_hash"],
135
+ "event_count": event_count,
136
+ }
137
+
138
+
139
+ def start(args: argparse.Namespace, store: StateStore) -> int:
140
+ if not args.project_dir.is_dir():
141
+ raise ValueError("project directory must exist and be a directory")
142
+ brief = args.redacted_brief_file.read_text(encoding="utf-8")
143
+ if not brief.strip():
144
+ raise ValueError("redacted brief file must not be empty")
145
+ secret_kind = likely_secret_kind(brief)
146
+ if secret_kind is not None:
147
+ raise ValueError(f"redacted brief rejected by likely-secret guard: {secret_kind}")
148
+ observed_snapshot = snapshot_hash(args.snapshot_hash)
149
+ identity, identity_mode = project_identity(args.project_dir, args.project_id)
150
+ run_id = f"run_{secrets.token_hex(12)}"
151
+ run = {
152
+ "schema_version": "5.0",
153
+ "run_id": run_id,
154
+ "project_key": project_key(identity),
155
+ "target_snapshot_hash": observed_snapshot,
156
+ "current_snapshot_hash": observed_snapshot,
157
+ "authorization_mode": "review-only",
158
+ "state": "DRAFT",
159
+ "outcome": "IN_PROGRESS",
160
+ "revision": 0,
161
+ "repair_cycle_count": 0,
162
+ "max_repair_cycles": 3,
163
+ "open_high_risk_assumptions": 0,
164
+ "retention_policy_version": "5.0",
165
+ }
166
+ created_at = now_epoch()
167
+ store.create_run(
168
+ run,
169
+ immutable_anchor={
170
+ "redacted_brief": brief,
171
+ "project_identity": identity,
172
+ "identity_mode": identity_mode,
173
+ "redaction_attestation": "caller-supplied-redacted-brief",
174
+ },
175
+ now=created_at,
176
+ )
177
+ lease = store.acquire_lease(run_id, f"m2-start-{secrets.token_hex(8)}", now=created_at)
178
+ ready = store.transition(
179
+ run_id,
180
+ expected_revision=0,
181
+ lease_token=lease["token"],
182
+ next_state="READY",
183
+ next_outcome="IN_PROGRESS",
184
+ observed_snapshot_hash=observed_snapshot,
185
+ now=created_at,
186
+ )
187
+ store.release_lease(run_id, lease["token"], now=created_at)
188
+ result = public_status(ready, len(store.list_events(run_id)))
189
+ result.update({"command": "start", "identity_mode": identity_mode, "next_action": "submit M3 review result"})
190
+ output(result)
191
+ return 0
192
+
193
+
194
+ def status(args: argparse.Namespace, store: StateStore) -> int:
195
+ run = store.get_run(args.run_id)
196
+ result = public_status(run, len(store.list_events(args.run_id)))
197
+ result["command"] = "status"
198
+ output(result)
199
+ return 0
200
+
201
+
202
+ def resume(args: argparse.Namespace, store: StateStore) -> int:
203
+ observed_snapshot = snapshot_hash(args.observed_snapshot_hash)
204
+ run = store.get_run(args.run_id)
205
+ if run["state"] in FINAL_STATES:
206
+ result = public_status(run, len(store.list_events(args.run_id)))
207
+ result.update({"command": "resume", "resume_disposition": "terminal-run-not-resumable"})
208
+ output(result)
209
+ return 0
210
+
211
+ checked_at = now_epoch()
212
+ lease = store.acquire_lease(args.run_id, f"m2-resume-{secrets.token_hex(8)}", now=checked_at)
213
+ try:
214
+ if observed_snapshot != run["current_snapshot_hash"]:
215
+ run = store.transition(
216
+ args.run_id,
217
+ expected_revision=run["revision"],
218
+ lease_token=lease["token"],
219
+ next_state=run["state"],
220
+ next_outcome=run["outcome"],
221
+ observed_snapshot_hash=observed_snapshot,
222
+ now=checked_at,
223
+ )
224
+ disposition = "snapshot-stale-new-run-required"
225
+ elif run["state"] == "READY":
226
+ disposition = "ready-for-review"
227
+ elif run["state"] == "NEEDS_USER_DECISION":
228
+ disposition = "awaiting-user-decision"
229
+ elif run["state"] == "BLOCKED":
230
+ if args.retry_blocked:
231
+ run = store.transition(
232
+ args.run_id,
233
+ expected_revision=run["revision"],
234
+ lease_token=lease["token"],
235
+ next_state="READY",
236
+ next_outcome="IN_PROGRESS",
237
+ observed_snapshot_hash=observed_snapshot,
238
+ now=checked_at,
239
+ )
240
+ disposition = "explicit-retry-authorized"
241
+ else:
242
+ disposition = "blocked-explicit-retry-required"
243
+ else:
244
+ disposition = "phase-adapter-required"
245
+ finally:
246
+ store.release_lease(args.run_id, lease["token"], now=checked_at)
247
+ result = public_status(run, len(store.list_events(args.run_id)))
248
+ result.update({"command": "resume", "resume_disposition": disposition})
249
+ output(result)
250
+ return 0
251
+
252
+
253
+ def review(args: argparse.Namespace, store: StateStore) -> int:
254
+ review_result = load_review_result(args.review_result_file)
255
+ result = ingest_review(
256
+ store,
257
+ args.run_id,
258
+ review_result,
259
+ snapshot_hash(args.observed_snapshot_hash),
260
+ args.redaction_status,
261
+ now_epoch(),
262
+ )
263
+ public = public_status(result["run"], len(store.list_events(args.run_id)))
264
+ public.update(
265
+ {
266
+ "command": "review",
267
+ "review_artifact_id": result["artifact_id"],
268
+ "new_finding_ids": result["new_finding_ids"],
269
+ "duplicate_finding_ids": result["duplicate_finding_ids"],
270
+ "no_material_delta_candidates": result["no_material_delta_candidates"],
271
+ }
272
+ )
273
+ output(public)
274
+ return 0
275
+
276
+
277
+ def patch_proposal(args: argparse.Namespace, store: StateStore) -> int:
278
+ proposal_result = load_patch_proposal(args.patch_proposal_file)
279
+ result = ingest_patch_proposal(
280
+ store,
281
+ args.run_id,
282
+ proposal_result,
283
+ snapshot_hash(args.observed_snapshot_hash),
284
+ args.redaction_status,
285
+ now_epoch(),
286
+ )
287
+ public = public_status(result["run"], len(store.list_events(args.run_id)))
288
+ public.update(
289
+ {
290
+ "command": "patch-proposal",
291
+ "proposal_artifact_id": result["artifact_id"],
292
+ "proposal_count": result["proposal_count"],
293
+ "recommended_proposal_count": result["recommended_proposal_count"],
294
+ "no_target_write_attestation": True,
295
+ }
296
+ )
297
+ output(public)
298
+ return 0
299
+
300
+
301
+ def host_execution_request(args: argparse.Namespace, store: StateStore) -> int:
302
+ observed_snapshot = snapshot_hash(args.observed_snapshot_hash)
303
+ request = HostExecutionRequest(args.run_id, args.artifact_file, observed_snapshot)
304
+ run = store.get_run(request.run_id)
305
+ if run["state"] != "READY" or run["current_snapshot_hash"] != request.observed_snapshot_hash:
306
+ raise ValueError("host execution request requires a READY run at its current snapshot")
307
+ public = public_status(run, len(store.list_events(request.run_id)))
308
+ public.update(
309
+ {
310
+ "command": "host-execution-request",
311
+ "disposition": "HOST_EXECUTOR_REQUIRED",
312
+ "execution_request": {
313
+ "run_id": request.run_id,
314
+ "artifact_file": str(request.artifact_file),
315
+ "observed_snapshot_hash": request.observed_snapshot_hash,
316
+ },
317
+ "no_model_call_attestation": True,
318
+ "no_target_write_attestation": True,
319
+ "external_command": "nlp-refinement-host review --allow-model-inference --run-id <run-id> --artifact-file <artifact.md-or-json> --observed-snapshot-hash <sha256>",
320
+ }
321
+ )
322
+ output(public)
323
+ return 0
324
+
325
+
326
+ def retention_preview(args: argparse.Namespace, store: StateStore) -> int:
327
+ now = args.now if args.now is not None else now_epoch()
328
+ plan = store.retention_preview(now)
329
+ output({"command": "retention-preview", **plan})
330
+ return 0
331
+
332
+
333
+ def retention_sweep(args: argparse.Namespace, store: StateStore) -> int:
334
+ now = args.now if args.now is not None else now_epoch()
335
+ applied = store.apply_retention(args.confirm_plan_hash, now)
336
+ output({"command": "retention-sweep", **applied})
337
+ return 0
338
+
339
+
340
+ def main(argv: list[str] | None = None) -> int:
341
+ args = build_parser().parse_args(argv)
342
+ store = StateStore(args.state_root / "state.db")
343
+ if args.command == "retention-preview" and not store.database_path.exists():
344
+ now = args.now if args.now is not None else now_epoch()
345
+ output({"command": "retention-preview", **store.empty_retention_preview(now)})
346
+ return 0
347
+ store.initialize()
348
+ try:
349
+ if args.command == "start":
350
+ return start(args, store)
351
+ if args.command == "status":
352
+ return status(args, store)
353
+ if args.command == "resume":
354
+ return resume(args, store)
355
+ if args.command == "review":
356
+ return review(args, store)
357
+ if args.command == "patch-proposal":
358
+ return patch_proposal(args, store)
359
+ if args.command == "host-execution-request":
360
+ return host_execution_request(args, store)
361
+ if args.command == "retention-preview":
362
+ return retention_preview(args, store)
363
+ if args.command == "retention-sweep":
364
+ return retention_sweep(args, store)
365
+ raise AssertionError(f"unsupported normal command: {args.command}")
366
+ except (KeyError, OSError, StateStoreError, ValueError) as error:
367
+ print(f"error: {error}", file=sys.stderr)
368
+ return 2
369
+
370
+
371
+ if __name__ == "__main__":
372
+ raise SystemExit(main())