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.
- nlp_refinement/__init__.py +1 -0
- nlp_refinement/diagnostic_doe_support.py +84 -0
- nlp_refinement/doe_receipt_retention.py +81 -0
- nlp_refinement/format_contracts.py +157 -0
- nlp_refinement/host_client.py +505 -0
- nlp_refinement/host_diagnostics.py +430 -0
- nlp_refinement/host_execution_request.py +15 -0
- nlp_refinement/host_executor.py +104 -0
- nlp_refinement/host_refine.py +82 -0
- nlp_refinement/m8_doe_fixtures.py +28 -0
- nlp_refinement/m8_review_coordinator.py +370 -0
- nlp_refinement/patch_proposal_adapter.py +303 -0
- nlp_refinement/refine.py +372 -0
- nlp_refinement/repair_feasibility.py +327 -0
- nlp_refinement/resources/__init__.py +0 -0
- nlp_refinement/resources/prompts/patch-proposal-phase.v5.md +51 -0
- nlp_refinement/resources/prompts/review-phase.v5.md +57 -0
- nlp_refinement/resources/schemas/v5/acceptance-trace.schema.json +17 -0
- nlp_refinement/resources/schemas/v5/artifact.schema.json +17 -0
- nlp_refinement/resources/schemas/v5/finding.schema.json +27 -0
- nlp_refinement/resources/schemas/v5/patch-proposal-result.schema.json +66 -0
- nlp_refinement/resources/schemas/v5/phase-envelope.schema.json +18 -0
- nlp_refinement/resources/schemas/v5/retention-policy.schema.json +16 -0
- nlp_refinement/resources/schemas/v5/review-result.schema.json +37 -0
- nlp_refinement/resources/schemas/v5/run.schema.json +22 -0
- nlp_refinement/review_adapter.py +203 -0
- nlp_refinement/sensitive_data.py +98 -0
- nlp_refinement/state_store.py +1025 -0
- nlp_refinement_cli-0.9.0.dist-info/METADATA +300 -0
- nlp_refinement_cli-0.9.0.dist-info/RECORD +35 -0
- nlp_refinement_cli-0.9.0.dist-info/WHEEL +5 -0
- nlp_refinement_cli-0.9.0.dist-info/entry_points.txt +4 -0
- nlp_refinement_cli-0.9.0.dist-info/licenses/LICENSE +201 -0
- nlp_refinement_cli-0.9.0.dist-info/licenses/NOTICE +4 -0
- nlp_refinement_cli-0.9.0.dist-info/top_level.txt +1 -0
nlp_refinement/refine.py
ADDED
|
@@ -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())
|