agent-apprenticeship 0.1.6 → 0.1.7

package/src/agent_apprenticeship_trace/mentor_checkpoints.py

@@ -43,6 +43,33 @@ def _attempt_summary(pkg: Path | None) -> dict[str, Any]:
     return {"attempts": len(attempts), "traced_steps": traced_steps, "artifacts": artifacts[:50]}
 
 
+def _mark_source_artifact_audited(pkg: Path | None, *, source: str, mode: str, input_source: str, stages: set[str]) -> None:
+    if not pkg:
+        return
+    updates = {
+        "mentor_audited": True,
+        "mentor_audit_source": source,
+        "audit_status": f"{mode}_audit_complete",
+        "checkpoint_input_source": input_source,
+    }
+    targets: list[Path] = []
+    if "task_intake" in stages:
+        targets.append(pkg / "task" / "task_intake_spec.json")
+    if "rubric" in stages:
+        targets.append(pkg / "rubric" / "rubric.json")
+    for path in targets:
+        if not path.exists():
+            continue
+        try:
+            data = read_json(path)
+            md = dict(data.get("metadata_json") or {})
+            md.update(updates)
+            data["metadata_json"] = md
+            write_json(path, data)
+        except Exception:
+            continue
+
+
 def _truthy_env(name: str) -> bool:
     return os.getenv(name, "").strip().lower() in {"1", "true", "yes", "on"}
 
@@ -81,7 +108,7 @@ def _parse_score(value: str, default: float) -> float:
     return max(0.0, min(1.0, score))
 
 
-APPROVE_WORDS = {"accept", "approve", "approved", "yes", "y", "ok", "okay"}
+APPROVE_WORDS = {"accept", "approve", "approved", "confirm", "confirmed", "yes", "y", "ok", "okay"}
 
 
 def _is_approve(value: str) -> bool:
@@ -103,42 +130,42 @@ def _collect_interactive_inputs(
     summary: dict[str, Any],
     stages: set[str],
 ) -> dict[str, Any]:
-    label = "Expert-led" if mode == "expert_led" else "Hybrid"
+    label = "Expert-led"
     default_passed = "pass" if status.get("task_status") == "completed" else "fail"
     default_score = "1.0" if default_passed == "pass" else "0.0"
     collected: dict[str, Any] = {}
     if "task_intake" in stages:
         print(f"{label} checkpoint: task intake")
-        intake_decision = _prompt("Approve or edit task intake", "approve")
+        intake_decision = _prompt("Confirm or edit task intake", "confirm")
         if _is_edit(intake_decision):
             edited_title = _prompt("Edited title, optional", "")
             intake_notes = _prompt("Task intake notes, optional", "")
             decision = "edited"
         else:
             edited_title = ""
-            intake_notes = "Approved as-is." if _is_approve(intake_decision) else f"Approved as-is. Input: {intake_decision}"
-            decision = "approved"
+            intake_notes = "Confirmed as-is." if _is_approve(intake_decision) else f"Confirmed as-is. Input: {intake_decision}"
+            decision = "confirmed"
         collected["task_intake"] = {
             "decision": decision,
             "edited_title": edited_title or None,
-            "notes": intake_notes or "Approved as-is.",
+            "notes": intake_notes or "Confirmed as-is.",
         }
 
     if "rubric" in stages:
         print(f"{label} checkpoint: rubric")
-        rubric_decision = _prompt("Approve or edit rubric", "approve")
+        rubric_decision = _prompt("Confirm or edit rubric", "confirm")
         if _is_edit(rubric_decision):
             additional_criterion = _prompt("Add rubric criterion, optional", "")
             rubric_notes = _prompt("Rubric notes, optional", "")
             rubric_choice = "edited"
         else:
             additional_criterion = ""
-            rubric_notes = "Rubric approved." if _is_approve(rubric_decision) else f"Rubric approved. Input: {rubric_decision}"
-            rubric_choice = "approved"
+            rubric_notes = "Rubric confirmed." if _is_approve(rubric_decision) else f"Rubric confirmed. Input: {rubric_decision}"
+            rubric_choice = "confirmed"
         collected["rubric"] = {
             "decision": rubric_choice,
             "additional_criteria": [additional_criterion] if additional_criterion else [],
-            "notes": rubric_notes or "Rubric approved.",
+            "notes": rubric_notes or "Rubric confirmed.",
         }
 
     if "evaluation" in stages:
@@ -168,12 +195,12 @@ def _collect_interactive_inputs(
 
     if "final_approval" in stages:
         print(f"{label} checkpoint: final bundle approval")
-        final_decision = _prompt("Approve final Contribution Bundle or hold", "approve").strip().lower()
+        final_decision = _prompt("Confirm final Experience Compilation or hold", "confirm").strip().lower()
         final_notes = _prompt("Final approval notes, optional", "")
         collected["final_approval"] = {
             "approved_for_local_bundle": _is_approve(final_decision) or final_decision.startswith("approve"),
-            "decision": "approved" if (_is_approve(final_decision) or final_decision.startswith("approve")) else "held",
-            "notes": final_notes or "Final Contribution Bundle checkpoint completed.",
+            "decision": "confirmed" if (_is_approve(final_decision) or final_decision.startswith("approve") or final_decision.startswith("confirm")) else "held",
+            "notes": final_notes or "Final Experience Compilation checkpoint completed.",
         }
 
     return collected
@@ -273,8 +300,8 @@ def write_mentor_checkpoints(
                 "checkpoint_type": "task_intake",
                 "title": intake_input.get("edited_title") or status.get("task_title"),
                 "instruction": session.get("task_instruction"),
-                "decision": intake_input.get("decision") or "approved",
-                "notes": intake_input.get("notes") or ("Approved as-is." if auto_approve else "Human expert checkpoint recorded."),
+                "decision": intake_input.get("decision") or "confirmed",
+                "notes": intake_input.get("notes") or ("Confirmed as-is." if auto_approve else "Human expert task-intake audit recorded."),
                 "checkpoint_input_source": input_source,
             },
             preserve_interactive=preserve_interactive,
@@ -290,9 +317,9 @@ def write_mentor_checkpoints(
                     "rubric/worker_visible_rubric.md",
                     "rubric/rubric.json",
                 ],
-                "decision": rubric_input.get("decision") or "approved",
+                "decision": rubric_input.get("decision") or "confirmed",
                 "additional_criteria": rubric_input.get("additional_criteria") or [],
-                "notes": rubric_input.get("notes") or ("Default/model-drafted rubric approved." if auto_approve else "Human expert rubric checkpoint recorded."),
+                "notes": rubric_input.get("notes") or ("Apprentice-generated rubric confirmed." if auto_approve else "Human expert rubric audit recorded."),
                 "checkpoint_input_source": input_source,
             },
             preserve_interactive=preserve_interactive,
@@ -340,15 +367,16 @@ def write_mentor_checkpoints(
                 "checkpoint_type": "final_approval",
                 "approved_for_local_bundle": final_input.get("approved_for_local_bundle", True),
                 "contribution_bundle_path": status.get("contribution_bundle_path"),
-                "decision": final_input.get("decision") or "approved",
-                "notes": final_input.get("notes") or "Final Contribution Bundle checkpoint recorded.",
+                "decision": final_input.get("decision") or "confirmed",
+                "notes": final_input.get("notes") or "Final Experience Compilation checkpoint recorded.",
                 "checkpoint_input_source": input_source,
             },
             preserve_interactive=preserve_interactive,
         )
     (root / "README.md").write_text(
         "# Mentor Checkpoints\n\n"
-        "These files record expert-led or hybrid human approval checkpoints for the apprenticeship session. "
-        "They are local review artifacts and do not contain raw provider secrets.\n"
+        "These files record expert-led or hybrid human audit checkpoints for the apprenticeship session. "
+        "They are local audit artifacts and do not contain raw provider secrets.\n"
     )
+    _mark_source_artifact_audited(pkg, source=source, mode=mode, input_source=input_source, stages=enabled_stages)
     return root

package/src/agent_apprenticeship_trace/openai_structured.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-import importlib, json, os, re, sys, time, urllib.error, urllib.parse, urllib.request
+import importlib, json, os, re, signal, sys, threading, time, urllib.error, urllib.parse, urllib.request
 from pathlib import Path
 from typing import Any
 from pydantic import BaseModel
@@ -150,6 +150,69 @@ def _provider_max_output_tokens() -> int:
         value = 2048
     return max(256, min(value, 4096))
 
+
+def _provider_request_timeout_seconds() -> int:
+    settings = get_settings()
+    raw = os.getenv("AA_ROLE_TIMEOUT_SECONDS") or os.getenv("AA_MODEL_ROLE_TIMEOUT_SECONDS")
+    if raw:
+        try:
+            return max(10, min(int(raw), settings.task_timeout_seconds))
+        except ValueError:
+            pass
+    return max(10, min(30, settings.task_timeout_seconds))
+
+
+def _provider_request_retry_count() -> int:
+    raw = os.getenv("AA_ROLE_RETRY_COUNT") or os.getenv("AA_MODEL_ROLE_RETRY_COUNT")
+    if raw:
+        try:
+            return max(1, min(int(raw), 3))
+        except ValueError:
+            pass
+    return 1
+
+
+def _provider_wall_timeout_seconds() -> int:
+    settings = get_settings()
+    raw = os.getenv("AA_ROLE_WALL_TIMEOUT_SECONDS") or os.getenv("AA_MODEL_ROLE_WALL_TIMEOUT_SECONDS")
+    if raw:
+        try:
+            return max(1, min(int(raw), settings.task_timeout_seconds))
+        except ValueError:
+            pass
+    return max(12, min(_provider_request_timeout_seconds() + 2, settings.task_timeout_seconds))
+
+
+def _with_wall_timeout(label: str, fn):
+    timeout = _provider_wall_timeout_seconds()
+    if threading.current_thread() is not threading.main_thread() or not hasattr(signal, "setitimer"):
+        return fn()
+    old_handler = signal.getsignal(signal.SIGALRM)
+    old_timer = signal.setitimer(signal.ITIMER_REAL, 0)
+
+    def _raise_timeout(_signum, _frame):
+        raise TimeoutError(f"{label} timed out after {timeout} seconds.")
+
+    try:
+        signal.signal(signal.SIGALRM, _raise_timeout)
+        signal.setitimer(signal.ITIMER_REAL, timeout)
+        return fn()
+    finally:
+        signal.setitimer(signal.ITIMER_REAL, 0)
+        signal.signal(signal.SIGALRM, old_handler)
+        if old_timer and old_timer[0] > 0:
+            signal.setitimer(signal.ITIMER_REAL, old_timer[0], old_timer[1])
+
+
+def _construct_openai_client(mod: Any, kwargs: dict[str, Any]) -> Any:
+    try:
+        return mod.OpenAI(**kwargs)
+    except TypeError as exc:
+        if "timeout" not in kwargs or "timeout" not in str(exc):
+            raise
+        return mod.OpenAI(**{k: v for k, v in kwargs.items() if k != "timeout"})
+
+
 def get_model_provider_status(provider_id: str | None = None) -> dict[str, Any]:
     provider_id = _configured_provider(provider_id)
     settings = get_settings()
@@ -182,7 +245,7 @@ def get_model_provider_status(provider_id: str | None = None) -> dict[str, Any]:
             kwargs = {"api_key": key}
             if provider_id in OPENAI_COMPATIBLE_BASE_URLS:
                 kwargs["base_url"] = OPENAI_COMPATIBLE_BASE_URLS[provider_id]
-            mod.OpenAI(**kwargs)
+            _construct_openai_client(mod, kwargs)
             status["client_constructed_ok"] = True
             status["provider_available"] = True
         except Exception as exc:
@@ -232,7 +295,7 @@ def _openai_compatible_response(provider_id: str, model_name: str, prompt: str)
     settings = get_settings()
     _env_var, key = _provider_key(provider_id, settings)
     mod = import_openai_sdk()
-    kwargs = {"api_key": key}
+    kwargs = {"api_key": key, "timeout": _provider_request_timeout_seconds()}
     if provider_id in OPENAI_COMPATIBLE_BASE_URLS:
         kwargs["base_url"] = OPENAI_COMPATIBLE_BASE_URLS[provider_id]
     if provider_id == "openrouter":
@@ -243,7 +306,7 @@ def _openai_compatible_response(provider_id: str, model_name: str, prompt: str)
             }
         except Exception:
             pass
-    client = mod.OpenAI(**kwargs)
+    client = _construct_openai_client(mod, kwargs)
     if provider_id == "openai":
         return _response_text(_responses_create_with_retry(client, model_name, prompt))
     response = client.chat.completions.create(
@@ -267,7 +330,7 @@ def _anthropic_response(model_name: str, prompt: str) -> str:
         "https://api.anthropic.com/v1/messages",
         {"x-api-key": key or "", "anthropic-version": "2023-06-01"},
         payload,
-        timeout=min(120, settings.task_timeout_seconds),
+        timeout=_provider_request_timeout_seconds(),
     )
     parts = data.get("content") or []
     text = "".join(str(part.get("text") or "") for part in parts if isinstance(part, dict))
@@ -284,7 +347,7 @@ def _google_response(model_name: str, prompt: str) -> str:
         "contents": [{"parts": [{"text": prompt}]}],
         "generationConfig": {"responseMimeType": "application/json", "maxOutputTokens": _provider_max_output_tokens()},
     }
-    data = _http_json(url, {}, payload, timeout=min(120, settings.task_timeout_seconds))
+    data = _http_json(url, {}, payload, timeout=_provider_request_timeout_seconds())
     try:
         return str(data["candidates"][0]["content"]["parts"][0]["text"])
     except Exception as exc:
@@ -301,13 +364,14 @@ def _provider_completion_text(provider_id: str, model_name: str, prompt: str) ->
 
 def _provider_completion_text_with_retry(provider_id: str, model_name: str, prompt: str) -> str:
     last: BaseException | None = None
-    for i in range(2):
+    attempts = _provider_request_retry_count()
+    for i in range(attempts):
         try:
             return _provider_completion_text(provider_id, model_name, prompt)
         except Exception as exc:
             last = exc
             kind, _msg = classify_model_provider_error(exc)
-            if i > 0 or kind in {"auth_error", "quota_or_credit_error", "bad_model"}:
+            if i >= attempts - 1 or kind in {"auth_error", "quota_or_credit_error", "bad_model"}:
                 raise
             time.sleep(0.75)
     raise last or RuntimeError("Mentor Model Provider request failed.")
@@ -402,7 +466,7 @@ def _transient_provider_error(exc: BaseException) -> bool:
     needles=['timeout','rate','temporar','connection reset','disconnect','websocket','service unavailable','gateway','overloaded']
     return any(n in name or n in msg for n in needles)
 
-def _responses_create_with_retry(client: Any, model_name: str, prompt: str, attempts: int = 3):
+def _responses_create_with_retry(client: Any, model_name: str, prompt: str, attempts: int = 1):
     last=None
     for i in range(attempts):
         try:
@@ -453,7 +517,10 @@ def run_structured_role(role: str, prompt: str, output_model: type[BaseModel], o
             raise RuntimeError(result.error_message)
         return result
     try:
-        raw=_provider_completion_text_with_retry(provider_id, model_name, prompt)
+        raw=_with_wall_timeout(
+            f"{status.get('provider_display') or provider_id} {role}",
+            lambda: _provider_completion_text_with_retry(provider_id, model_name, prompt),
+        )
         (out_dir/'raw_output.txt').write_text(redact_secrets(raw))
         try:
             normalized,json_meta,normalized_used=_validate_role_output(role, raw, output_model, normalizer_context, out_dir)
@@ -464,7 +531,10 @@ def run_structured_role(role: str, prompt: str, output_model: type[BaseModel], o
             retry_raw=None
             try:
                 retry_prompt=_strict_json_retry_prompt(role, prompt, first_error)
-                retry_raw=_provider_completion_text_with_retry(provider_id, model_name, retry_prompt)
+                retry_raw=_with_wall_timeout(
+                    f"{status.get('provider_display') or provider_id} {role} structured retry",
+                    lambda: _provider_completion_text_with_retry(provider_id, model_name, retry_prompt),
+                )
                 (out_dir/'raw_output.retry.txt').write_text(redact_secrets(retry_raw))
                 normalized,json_meta,normalized_used=_validate_role_output(role, retry_raw, output_model, normalizer_context, out_dir)
                 write_json(out_dir/'parsed_output.json', normalized)
@@ -520,7 +590,7 @@ def smoke_prompts() -> dict[str, tuple[str, type[BaseModel]]]:
         "pass_threshold": 0.7,
         "observable_evidence": ["artifacts/hello.txt"],
         "required_artifacts": ["hello.txt"],
-        "scoring_method": "deterministic",
+        "scoring_method": "hybrid",
         "worker_visible": True,
         "verifier_only": False,
         "hidden_reference_required": False,
@@ -613,8 +683,8 @@ def smoke_prompts() -> dict[str, tuple[str, type[BaseModel]]]:
                 "required_artifacts": ["hello.txt"],
                 "disqualifying_errors": [],
                 "partial_credit_allowed": True,
-                "grader_kind": "deterministic",
-                "rubric_generation_source": "deterministic_seed",
+                "grader_kind": "hybrid",
+                "rubric_generation_source": "agent_assisted",
                 "rubric_generation_agent_provider": None,
                 "rubric_generation_agent_model": None,
                 "rubric_generation_confidence": 0.9,

package/src/agent_apprenticeship_trace/package_exporter.py

@@ -7,7 +7,7 @@ from .rubric_generation import worker_visible_markdown
 from .artifact_resolver import artifact_ref_candidates, normalize_artifact_ref
 
 
-SOURCE_FIELD_KEYS={'source_url_or_ref','source_kind','source_url','source_ref','source_license'}
+SOURCE_FIELD_KEYS={'source_url_or_ref','source_kind','source_url','source_ref','source_basis','source_license'}
 IGNORED_RELEASE_DIR_NAMES={
     'node_modules','.venv','__pycache__','.pytest_cache','.mypy_cache','.ruff_cache','.git','.cache','dist','build'
 }

package/src/agent_apprenticeship_trace/progress.py

@@ -52,6 +52,7 @@ def _base_status(run_id: str, run_root: Path, **kwargs: Any) -> dict[str, Any]:
         "maximum_improvement_loops": kwargs.get("maximum_improvement_loops"),
         "latest_message": kwargs.get("latest_message") or "Run starting.",
         "apprentice_agent": kwargs.get("apprentice_agent") or kwargs.get("worker_agent"),
+        "apprenticeship_mode": kwargs.get("apprenticeship_mode"),
         "mentor_mode": kwargs.get("mentor_mode"),
         "task_title": kwargs.get("task_title"),
         "task_workspace_path": str(kwargs.get("task_workspace_path") or run_root),
@@ -191,7 +192,7 @@ def format_run_status(status: dict[str, Any]) -> str:
         f"Artifacts: {status.get('artifacts_path')}",
     ]
     if status.get("contribution_bundle_path"):
-        lines.append(f"Contribution Bundle: {status.get('contribution_bundle_path')}")
+        lines.append(f"Experience Compilation: {status.get('contribution_bundle_path')}")
     if status.get("traced_steps") is not None:
         lines.append(f"Traced Steps: {status.get('traced_steps')}")
     if status.get("artifact_count") is not None: