cluxion-agentplugin-preprocessing 0.2.0__py3-none-any.whl

cluxion_runtime/core/clarification.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+"""Deterministic ambiguity detection and user clarification before queueing."""
+
+from dataclasses import dataclass
+
+from cluxion_runtime.core.types import WorkIntent, WorkItem
+
+
+@dataclass(frozen=True)
+class ClarificationQuestion:
+    """Single question the host agent must ask the user."""
+
+    question_id: str
+    prompt: str
+    why: str
+    blocking: bool = True
+
+
+@dataclass(frozen=True)
+class ClarificationResult:
+    """Whether work can proceed or must ask the user first."""
+
+    required: bool
+    ready_for_queue: bool
+    reason_codes: tuple[str, ...]
+    questions: tuple[ClarificationQuestion, ...]
+    resolved_direction: str = ""
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "required": self.required,
+            "ready_for_queue": self.ready_for_queue,
+            "reason_codes": list(self.reason_codes),
+            "resolved_direction": self.resolved_direction,
+            "questions": [
+                {
+                    "question_id": question.question_id,
+                    "prompt": question.prompt,
+                    "why": question.why,
+                    "blocking": question.blocking,
+                }
+                for question in self.questions
+            ],
+        }
+
+
+_AMBIGUOUS_KEYWORDS = (
+    "maybe",
+    "perhaps",
+    "either",
+    "or",
+    "not sure",
+    "unsure",
+    "아마",
+    "어느",
+    "둘 중",
+    "모르겠",
+    "헷갈",
+    "애매",
+)
+_SCOPE_KEYWORDS = ("all", "everything", "전부", "전체", "모든")
+_TARGET_MISSING_KEYWORDS = ("fix", "implement", "refactor", "patch", "수정", "구현", "리팩터", "패치")
+_LOW_CONFIDENCE_THRESHOLD = 0.62
+
+
+def assess_clarification(item: WorkItem, intent: WorkIntent) -> ClarificationResult:
+    """Decide whether the host agent must ask the user before queueing work."""
+    text = item.prompt.lower()
+    reasons: list[str] = []
+    questions: list[ClarificationQuestion] = []
+
+    if intent.confidence < _LOW_CONFIDENCE_THRESHOLD and _needs_direction_confirmation(text, intent):
+        reasons.append("low_intent_confidence")
+        questions.append(
+            ClarificationQuestion(
+                "intent_direction",
+                "어떤 방향으로 진행할지 한 문장으로 확정해 주세요. (예: 버그 수정 / 문서 작성 / 조사만)",
+                "요청 의도가 여러 갈래로 해석될 수 있습니다.",
+            )
+        )
+
+    if _has_any(text, _AMBIGUOUS_KEYWORDS):
+        reasons.append("ambiguous_language")
+        questions.append(
+            ClarificationQuestion(
+                "disambiguate_choice",
+                "애매한 표현이 있습니다. 원하는 결과를 A/B 중 하나로 골라 주시거나, 우선순위를 명시해 주세요.",
+                "모호한 지시는 잘못된 작업큐로 이어질 수 있습니다.",
+            )
+        )
+
+    if intent.category == "engineering" and _looks_like_coding_without_target(text):
+        reasons.append("missing_target_scope")
+        questions.append(
+            ClarificationQuestion(
+                "target_scope",
+                "어떤 파일/모듈/기능을 대상으로 할까요? 경로나 심볼 이름을 알려 주세요.",
+                "코딩 작업인데 변경 대상이 명시되지 않았습니다.",
+            )
+        )
+
+    if _has_any(text, _SCOPE_KEYWORDS) and not _has_any(text, ("repo", "project", "directory", "레포", "프로젝트", "폴더")):
+        reasons.append("broad_scope_without_boundary")
+        questions.append(
+            ClarificationQuestion(
+                "scope_boundary",
+                "범위가 넓어 보입니다. 포함/제외할 경로나 컴포넌트를 지정해 주세요.",
+                "전체 범위 작업은 실패하거나 과도한 비용이 들 수 있습니다.",
+            )
+        )
+
+    if _conflicting_signals(text, intent):
+        reasons.append("conflicting_signals")
+        questions.append(
+            ClarificationQuestion(
+                "resolve_conflict",
+                "서로 다른 작업 유형 신호가 감지됐습니다. 이번 턴의 1순위 목표를 하나만 선택해 주세요.",
+                "동시에 여러 종류의 작업으로 해석됩니다.",
+            )
+        )
+
+    if item.metadata.get("clarification_answers"):
+        return ClarificationResult(
+            required=False,
+            ready_for_queue=True,
+            reason_codes=("user_clarified",),
+            questions=(),
+            resolved_direction=item.metadata.get("clarification_answers", ""),
+        )
+
+    if not questions:
+        return ClarificationResult(
+            required=False,
+            ready_for_queue=True,
+            reason_codes=("direction_clear",),
+            questions=(),
+            resolved_direction=intent.direction,
+        )
+
+    deduped = _dedupe_questions(questions)
+    return ClarificationResult(
+        required=True,
+        ready_for_queue=False,
+        reason_codes=tuple(dict.fromkeys(reasons)),
+        questions=tuple(deduped),
+        resolved_direction="",
+    )
+
+
+def _needs_direction_confirmation(text: str, intent: WorkIntent) -> bool:
+    if intent.category == "general" and len(text) < 240:
+        return False
+    if _has_any(text, _AMBIGUOUS_KEYWORDS):
+        return True
+    if intent.category in {"engineering", "security", "documentation", "local_model"}:
+        return True
+    return len(text) > 400
+
+
+def _looks_like_coding_without_target(text: str) -> bool:
+    if not _has_any(text, _TARGET_MISSING_KEYWORDS):
+        return False
+    target_markers = (".py", ".rs", ".ts", ".js", "/", "\\", "src/", "tests/", "파일", "모듈", "함수", "class ")
+    return not _has_any(text, target_markers)
+
+
+def _conflicting_signals(text: str, intent: WorkIntent) -> bool:
+    coding = _has_any(text, ("code", "implement", "fix", "patch", "코드", "구현", "수정"))
+    docs = _has_any(text, ("docs", "readme", "문서", "가이드"))
+    security = _has_any(text, ("security", "audit", "보안", "취약점"))
+    local = intent.local_model_requested or _has_any(text, ("local model", "vllm", "로컬"))
+    active = sum(signal for signal in (coding, docs, security, local) if signal)
+    return active >= 2 and intent.confidence < 0.8
+
+
+def _dedupe_questions(questions: list[ClarificationQuestion]) -> list[ClarificationQuestion]:
+    seen: set[str] = set()
+    unique: list[ClarificationQuestion] = []
+    for question in questions:
+        if question.question_id in seen:
+            continue
+        seen.add(question.question_id)
+        unique.append(question)
+    return unique
+
+
+def _has_any(text: str, needles: tuple[str, ...]) -> bool:
+    return any(needle in text for needle in needles)
+
+
+__all__ = ["ClarificationQuestion", "ClarificationResult", "assess_clarification"]

cluxion_runtime/core/dispatch_store.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+"""Hermes host-model segment dispatch를 위한 작은 파일 기반 저장소."""
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cluxion_runtime.core.types import HarnessPlan, QueueSegment
+
+DISPATCH_DIR_ENV = "CLUXION_PREPROCESS_DISPATCH_DIR"
+_LEGACY_DISPATCH_DIR_ENV = "HERMES_CLUXION_DISPATCH_DIR"
+_DEFAULT_BASE_DIR = Path.home() / ".local" / "share" / "cluxion-agentplugin-preprocessing" / "queue" / "dispatch"
+
+
+@dataclass(frozen=True)
+class DispatchStepRecord:
+    """저장된 segment 실행 단계."""
+
+    step_id: str
+    segment_id: str
+    checksum: str
+    token_estimate: int
+    content: str
+    status: str
+    result: str = ""
+    error: str = ""
+
+
+class DispatchStoreError(RuntimeError):
+    """dispatch bundle이 없거나 손상된 경우."""
+
+
+def default_dispatch_dir() -> Path:
+    """사용자별 dispatch 저장 경로를 반환한다."""
+    for env_name in (DISPATCH_DIR_ENV, _LEGACY_DISPATCH_DIR_ENV):
+        value = os.environ.get(env_name, "").strip()
+        if value:
+            return Path(value).expanduser()
+    return _DEFAULT_BASE_DIR
+
+
+def persist_dispatch_bundle(plan: HarnessPlan, *, dispatch_dir: Path | None = None) -> Path | None:
+    """queue가 필요한 plan만 segment content를 별도 bundle로 저장한다."""
+    if not plan.execution.queue_required:
+        return None
+    bundle = _bundle_from_plan(plan)
+    target_dir = default_dispatch_dir() if dispatch_dir is None else dispatch_dir
+    if plan.queue_backend == "rust" and dispatch_dir is None and not _custom_dispatch_dir_configured():
+        try:
+            from cluxion_runtime.resources.queue_bridge import default_store_dir
+            from cluxion_runtime.resources.queue_bridge import persist_dispatch_bundle as rust_persist
+
+            result = rust_persist(plan.item.work_id, bundle, store_dir=default_store_dir())
+            if result.get("ok") and result.get("stored"):
+                return Path(str(result.get("path", "")))
+        except RuntimeError:
+            pass
+    target_dir.mkdir(parents=True, exist_ok=True)
+    path = _bundle_path(plan.item.work_id, target_dir)
+    _atomic_write_json(path, bundle)
+    return path
+
+
+def load_dispatch_bundle(work_id: str, *, dispatch_dir: Path | None = None) -> dict[str, object]:
+    """work_id에 해당하는 dispatch bundle을 읽는다."""
+    path = _bundle_path(work_id, default_dispatch_dir() if dispatch_dir is None else dispatch_dir)
+    if not path.exists():
+        raise DispatchStoreError(f"dispatch bundle not found: {work_id}")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise DispatchStoreError(f"dispatch bundle is invalid JSON: {work_id}") from exc
+    if not isinstance(payload, dict):
+        raise DispatchStoreError(f"dispatch bundle must be an object: {work_id}")
+    return payload
+
+
+def next_dispatch_step(work_id: str, *, dispatch_dir: Path | None = None) -> dict[str, object]:
+    """다음 queued segment를 running으로 표시하고 Hermes가 처리할 payload를 반환한다."""
+    target_dir = default_dispatch_dir() if dispatch_dir is None else dispatch_dir
+    bundle = load_dispatch_bundle(work_id, dispatch_dir=target_dir)
+    steps = _steps(bundle)
+    for step in steps:
+        if step.get("status") in {"queued", "retry_wait"}:
+            step["status"] = "running"
+            step["updated_at"] = time.time()
+            _atomic_write_json(_bundle_path(work_id, target_dir), bundle)
+            return {
+                "work_id": work_id,
+                "ready": True,
+                "step": _public_step(step),
+                "remaining": _remaining_count(steps),
+                "synthesis_ready": False,
+            }
+    return {
+        "work_id": work_id,
+        "ready": False,
+        "step": {},
+        "remaining": _remaining_count(steps),
+        "synthesis_ready": all(step.get("status") == "succeeded" for step in steps),
+    }
+
+
+def record_dispatch_result(
+    work_id: str,
+    step_id: str,
+    *,
+    result: str = "",
+    error: str = "",
+    succeeded: bool = True,
+    dispatch_dir: Path | None = None,
+) -> dict[str, object]:
+    """Hermes 모델이 처리한 segment 결과를 저장한다."""
+    target_dir = default_dispatch_dir() if dispatch_dir is None else dispatch_dir
+    bundle = load_dispatch_bundle(work_id, dispatch_dir=target_dir)
+    steps = _steps(bundle)
+    for step in steps:
+        if step.get("step_id") == step_id:
+            step["status"] = "succeeded" if succeeded else "failed"
+            step["result"] = result
+            step["error"] = error
+            step["updated_at"] = time.time()
+            _atomic_write_json(_bundle_path(work_id, target_dir), bundle)
+            return {
+                "work_id": work_id,
+                "step_id": step_id,
+                "recorded": True,
+                "status": step["status"],
+                "remaining": _remaining_count(steps),
+                "synthesis_ready": all(item.get("status") == "succeeded" for item in steps),
+            }
+    raise DispatchStoreError(f"dispatch step not found: {work_id}/{step_id}")
+
+
+def build_briefing_payload(work_id: str, *, dispatch_dir: Path | None = None) -> dict[str, object]:
+    """모든 segment 결과를 최종 보고용 synthesis prompt로 묶는다."""
+    bundle = load_dispatch_bundle(work_id, dispatch_dir=dispatch_dir)
+    steps = _steps(bundle)
+    missing = [str(step.get("step_id", "")) for step in steps if step.get("status") != "succeeded"]
+    if missing:
+        return {"work_id": work_id, "ready": False, "missing_steps": missing, "briefing_prompt": ""}
+    prompt = _briefing_prompt(bundle, steps)
+    return {
+        "work_id": work_id,
+        "ready": True,
+        "missing_steps": [],
+        "briefing_prompt": prompt,
+        "result_count": len(steps),
+    }
+
+
+def _bundle_from_plan(plan: HarnessPlan) -> dict[str, object]:
+    return {
+        "schema_version": 1,
+        "created_at": time.time(),
+        "work_id": plan.item.work_id,
+        "surface": plan.item.surface.value,
+        "original_prompt_preview": plan.preprocessing.normalized_prompt,
+        "answer_policy": {
+            "response_contract": plan.preprocessing.answer_policy.response_contract,
+            "required_checks": list(plan.preprocessing.answer_policy.required_checks),
+            "rules": list(plan.preprocessing.answer_policy.rules),
+        },
+        "steps": [_step_from_segment(segment) for segment in plan.preprocessing.segments],
+    }
+
+
+def _step_from_segment(segment: QueueSegment) -> dict[str, object]:
+    return {
+        "step_id": f"exec_{segment.segment_id}",
+        "segment_id": segment.segment_id,
+        "checksum": segment.checksum,
+        "token_estimate": segment.token_estimate,
+        "content": segment.content,
+        "status": "queued",
+        "result": "",
+        "error": "",
+        "updated_at": time.time(),
+    }
+
+
+def _public_step(step: dict[str, object]) -> dict[str, object]:
+    content = str(step.get("content", ""))
+    return {
+        "step_id": str(step.get("step_id", "")),
+        "segment_id": str(step.get("segment_id", "")),
+        "checksum": str(step.get("checksum", "")),
+        "token_estimate": int(step.get("token_estimate", 0)),
+        "content": content,
+        "instruction": (
+            "Process this segment with the current Hermes model. Preserve the checksum, "
+            "return only segment-grounded findings, and do not claim checks were run unless they were run."
+        ),
+    }
+
+
+def _briefing_prompt(bundle: dict[str, object], steps: list[dict[str, object]]) -> str:
+    lines = [
+        "[cluxion_final_briefing]",
+        f"work_id={bundle.get('work_id', '')}",
+        "Synthesize the ordered segment results into a concise user-facing briefing.",
+        "Separate verified facts, tool results, inferences, missing checks, and remaining risks.",
+        "[segment_results]",
+    ]
+    for step in steps:
+        lines.append(
+            "\n".join(
+                [
+                    f"step_id={step.get('step_id', '')}",
+                    f"segment_id={step.get('segment_id', '')}",
+                    f"checksum={step.get('checksum', '')}",
+                    str(step.get("result", "")),
+                ]
+            )
+        )
+    return "\n\n".join(lines)
+
+
+def _steps(bundle: dict[str, object]) -> list[dict[str, object]]:
+    steps = bundle.get("steps")
+    if not isinstance(steps, list):
+        raise DispatchStoreError("dispatch bundle has no steps array")
+    if not all(isinstance(step, dict) for step in steps):
+        raise DispatchStoreError("dispatch bundle steps must be objects")
+    return steps
+
+
+def _remaining_count(steps: list[dict[str, object]]) -> int:
+    return sum(1 for step in steps if step.get("status") in {"queued", "retry_wait", "running"})
+
+
+def _custom_dispatch_dir_configured() -> bool:
+    return bool(os.environ.get(DISPATCH_DIR_ENV, "").strip() or os.environ.get(_LEGACY_DISPATCH_DIR_ENV, "").strip())
+
+
+def _bundle_path(work_id: str, dispatch_dir: Path) -> Path:
+    safe = "".join(ch for ch in work_id if ch.isalnum() or ch in {"-", "_"})
+    if not safe:
+        raise DispatchStoreError("work_id is empty")
+    return dispatch_dir / f"{safe}.json"
+
+
+def _atomic_write_json(path: Path, payload: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as handle:
+        json.dump(payload, handle, ensure_ascii=False, sort_keys=True)
+        handle.write("\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+        temporary = Path(handle.name)
+    temporary.replace(path)
+
+
+__all__ = [
+    "DISPATCH_DIR_ENV",
+    "DispatchStepRecord",
+    "DispatchStoreError",
+    "build_briefing_payload",
+    "default_dispatch_dir",
+    "load_dispatch_bundle",
+    "next_dispatch_step",
+    "persist_dispatch_bundle",
+    "record_dispatch_result",
+]