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

cluxion_runtime/core/harness.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+"""전처리, 작업큐, Rust admission, 로컬 모델 프로필을 묶는 하네스."""
+
+from cluxion_runtime.core.clarification import assess_clarification
+from cluxion_runtime.core.intent import classify_intent
+from cluxion_runtime.core.preprocess import preprocess_work
+from cluxion_runtime.core.types import (
+    AgentSurface,
+    HarnessPlan,
+    HostExecutionPlan,
+    HostExecutionStep,
+    ModelRuntimeProfile,
+    PreprocessResult,
+    ResourceDecision,
+    ResourceSnapshot,
+    RuntimeKind,
+    WorkItem,
+)
+from cluxion_runtime.models.vllm_mlx import select_mac_local_profile
+from cluxion_runtime.resources.queue_bridge import queue_available
+from cluxion_runtime.resources.rust_bridge import capacity_decision, collect_resource_snapshot
+
+
+def build_harness_plan(
+    item: WorkItem,
+    *,
+    snapshot: ResourceSnapshot | None = None,
+    queue_position: int = 0,
+) -> HarnessPlan:
+    """외부 에이전트 요청을 Cluxion 내부 실행 계획으로 변환한다."""
+    intent = classify_intent(item)
+    clarification = assess_clarification(item, intent)
+    if clarification.required:
+        preprocessed = preprocess_work(
+            item,
+            intent_category=intent.category,
+            local_model_requested=intent.local_model_requested,
+            force_mode="needs_clarification",
+        )
+        runtime = _runtime_profile_for(item)
+        return HarnessPlan(
+            item=item,
+            intent=intent,
+            preprocessing=preprocessed,
+            resource=_fast_answer_decision("needs_clarification"),
+            runtime=runtime,
+            execution=_clarification_execution_plan(item, clarification),
+            queue_position=queue_position,
+            clarification_required=True,
+            clarification_questions=tuple(question.prompt for question in clarification.questions),
+            queue_backend="rust" if queue_available() else "python",
+        )
+    work_kind = _work_kind_for(item, intent_category=intent.category)
+    preprocessed = preprocess_work(
+        item,
+        intent_category=intent.category,
+        local_model_requested=intent.local_model_requested,
+    )
+    runtime = _runtime_profile_for(item)
+    resource = (
+        _fast_answer_decision(preprocessed.mode)
+        if _uses_fast_answer_resource_path(preprocessed.mode, runtime.kind)
+        else _capacity_decision_for(item, preprocessed.token_estimate, work_kind=work_kind, snapshot=snapshot)
+    )
+    return HarnessPlan(
+        item=item,
+        intent=intent,
+        preprocessing=preprocessed,
+        resource=resource,
+        runtime=runtime,
+        execution=_host_execution_plan_for(item, preprocessed, runtime),
+        queue_position=queue_position,
+        clarification_required=False,
+        queue_backend="rust" if queue_available() else "python",
+    )
+
+
+def _clarification_execution_plan(item: WorkItem, clarification: object) -> HostExecutionPlan:
+    questions = getattr(clarification, "questions", ())
+    question_lines = "\n".join(f"- {question.prompt}" for question in questions)
+    prompt = (
+        "[cluxion_needs_clarification]\n"
+        "Do not guess or start work yet. Ask the user these questions and wait for answers.\n"
+        "If you still do not know after available context, say you do not know.\n"
+        f"{question_lines}"
+    )
+    return HostExecutionPlan(
+        model_owner="host_current_model",
+        provider_policy="ask_user_before_queue; do_not_enqueue_until_direction_is_clear",
+        strategy="ask_user_before_queue",
+        queue_required=False,
+        synthesis_required=False,
+        preflight_required=False,
+        max_extra_model_calls=0,
+        steps=(
+            HostExecutionStep(
+                "clarify",
+                "ask_user_questions",
+                prompt,
+                required_checks=("say_unknown_if_insufficient_context", "do_not_start_work_without_user_direction"),
+            ),
+        ),
+        performance_notes=("clarification_blocks_queue_until_user_answers",),
+    )
+
+
+def _host_execution_plan_for(
+    item: WorkItem,
+    preprocessed: PreprocessResult,
+    runtime: ModelRuntimeProfile,
+) -> HostExecutionPlan:
+    mode = preprocessed.mode
+    policy = preprocessed.answer_policy
+    if runtime.kind == RuntimeKind.HOST_MANAGED:
+        provider_policy = (
+            "use_current_hermes_model_and_oauth; cluxion_must_not_call_or_configure_cloud_model_provider"
+            if item.surface == AgentSurface.HERMES
+            else "use_current_host_agent_model; cluxion_only_returns_execution_contract"
+        )
+    else:
+        provider_policy = (
+            "start_or_verify_cluxion_local_endpoint_then_switch_hermes_to_custom_provider; "
+            "all_completion_calls_still_belong_to_hermes"
+        )
+    base_notes = (
+        "simple_and_verification_modes_skip_resource_snapshot",
+        "do_not_add_extra_model_call_unless_queue_requires_segment_processing",
+    )
+    if mode == "simple_answer":
+        return HostExecutionPlan(
+            model_owner="hermes_current_model" if item.surface == AgentSurface.HERMES else "host_current_model",
+            provider_policy=provider_policy,
+            strategy="current_turn_direct_answer",
+            queue_required=False,
+            synthesis_required=False,
+            preflight_required=False,
+            max_extra_model_calls=0,
+            steps=(
+                HostExecutionStep(
+                    "answer",
+                    "direct_answer",
+                    item.prompt,
+                    required_checks=policy.required_checks,
+                    token_estimate=preprocessed.token_estimate,
+                ),
+            ),
+            performance_notes=base_notes,
+        )
+    if mode == "verification_answer":
+        return HostExecutionPlan(
+            model_owner="hermes_current_model" if item.surface == AgentSurface.HERMES else "host_current_model",
+            provider_policy=provider_policy,
+            strategy="current_turn_verify_then_answer",
+            queue_required=False,
+            synthesis_required=False,
+            preflight_required=False,
+            max_extra_model_calls=0,
+            steps=(
+                HostExecutionStep(
+                    "verify",
+                    "verify_then_answer",
+                    item.prompt,
+                    required_checks=policy.required_checks,
+                    token_estimate=preprocessed.token_estimate,
+                ),
+            ),
+            performance_notes=base_notes,
+        )
+    if mode == "queued":
+        segment_steps = tuple(
+            HostExecutionStep(
+                f"exec_{segment.segment_id}",
+                "execute_segment",
+                "Fetch this step through cluxion_queue_next, process it with the current Hermes model, "
+                "then store the result with cluxion_queue_record.",
+                segment_id=segment.segment_id,
+                checksum=segment.checksum,
+                token_estimate=segment.token_estimate,
+                required_checks=policy.required_checks,
+            )
+            for segment in preprocessed.segments
+        )
+        final_step = HostExecutionStep(
+            "brief",
+            "synthesize_briefing",
+            "After all segment steps are recorded, call cluxion_queue_brief and answer from its briefing_prompt.",
+            depends_on=tuple(step.step_id for step in segment_steps),
+            required_checks=policy.required_checks,
+            token_estimate=preprocessed.token_estimate,
+        )
+        return HostExecutionPlan(
+            model_owner="hermes_current_model" if item.surface == AgentSurface.HERMES else "host_current_model",
+            provider_policy=provider_policy,
+            strategy="durable_segment_queue",
+            queue_required=True,
+            synthesis_required=True,
+            preflight_required=False,
+            max_extra_model_calls=len(segment_steps) + 1,
+            steps=(*segment_steps, final_step),
+            next_tool="cluxion_queue_next",
+            record_tool="cluxion_queue_record",
+            brief_tool="cluxion_queue_brief",
+            performance_notes=(
+                *base_notes,
+                "queued_plan_stores_segment_content_out_of_band",
+                "initial_plan_returns_metadata_not_full_segment_payload",
+            ),
+        )
+    return HostExecutionPlan(
+        model_owner="hermes_current_model" if item.surface == AgentSurface.HERMES else "host_current_model",
+        provider_policy=provider_policy,
+        strategy="single_host_task",
+        queue_required=False,
+        synthesis_required=False,
+        preflight_required=False,
+        max_extra_model_calls=0,
+        steps=(
+            HostExecutionStep(
+                "execute",
+                "execute_task",
+                preprocessed.normalized_prompt,
+                required_checks=policy.required_checks,
+                token_estimate=preprocessed.token_estimate,
+            ),
+        ),
+        performance_notes=base_notes,
+    )
+
+
+def _capacity_decision_for(
+    item: WorkItem,
+    token_estimate: int,
+    *,
+    work_kind: str,
+    snapshot: ResourceSnapshot | None,
+) -> ResourceDecision:
+    current = collect_resource_snapshot() if snapshot is None else snapshot
+    return capacity_decision(
+        work_kind,
+        current,
+        expected_ram_mb=_expected_ram(item, token_estimate),
+    )
+
+
+def _uses_fast_answer_resource_path(mode: str, runtime_kind: RuntimeKind) -> bool:
+    return mode in {"simple_answer", "verification_answer"} and runtime_kind == RuntimeKind.HOST_MANAGED
+
+
+def _fast_answer_decision(mode: str) -> ResourceDecision:
+    reason = "verification_required" if mode == "verification_answer" else "preprocess_not_required"
+    return ResourceDecision(
+        True,
+        mode,
+        reason,
+        1,
+        mode,
+        0,
+        ("fast_path", "resource_snapshot_skipped"),
+    )
+
+
+def _work_kind_for(item: WorkItem, *, intent_category: str) -> str:
+    route = item.model_route.lower()
+    if _explicit_local_route(route):
+        return "qwen"
+    if intent_category == "security":
+        return "security"
+    if item.surface == AgentSurface.CODEX:
+        return "codex"
+    if item.surface == AgentSurface.GROK_BUILD:
+        return "grok"
+    if item.surface == AgentSurface.CLAUDE:
+        return "claude"
+    return "generic"
+
+
+def _expected_ram(item: WorkItem, token_estimate: int) -> int:
+    if item.expected_ram_mb > 0:
+        return item.expected_ram_mb
+    if not _explicit_local_route(item.model_route.lower()):
+        return 512
+    route = item.model_route.lower()
+    if "35b" in route or "32b" in route:
+        return 24_000
+    if "14b" in route or "13b" in route:
+        return 12_000
+    if "7b" in route or "8b" in route:
+        return 8_000
+    return 2_000 + min(8_000, token_estimate // 2)
+
+
+def _model_name(model_route: str) -> str:
+    for prefix in ("local/", "mlx/", "vllm-mlx/", "vllm_mlx/"):
+        if model_route.startswith(prefix):
+            return model_route.removeprefix(prefix)
+    return model_route
+
+
+def _runtime_profile_for(item: WorkItem) -> ModelRuntimeProfile:
+    if not _explicit_local_route(item.model_route.lower()):
+        return _host_managed_profile(item)
+    return select_mac_local_profile(_model_name(item.model_route))
+
+
+def _host_managed_profile(item: WorkItem) -> ModelRuntimeProfile:
+    return ModelRuntimeProfile(
+        kind=RuntimeKind.HOST_MANAGED,
+        model=item.model_route,
+        base_url="",
+        command=(),
+        health_path="",
+    )
+
+
+def _explicit_local_route(route: str) -> bool:
+    return route.startswith(("local/", "mlx/", "vllm-mlx/", "vllm_mlx/")) and route != "local/default"
+
+
+__all__ = ["build_harness_plan"]

cluxion_runtime/core/intent.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+"""Deterministic intent and direction classification for agent work."""
+
+from cluxion_runtime.core.types import AgentSurface, WorkIntent, WorkItem
+
+
+def classify_intent(item: WorkItem) -> WorkIntent:
+    """Classify user intent before the host model spends context."""
+    text = f"{item.prompt}\n{item.model_route}".lower()
+    signals: list[str] = []
+    local = _has_any(text, ("vllm-mlx", "mlx", "local model", "로컬모델", "로컬 모델", "serve-local"))
+    if item.model_route.lower().startswith(("local/", "mlx/", "vllm-mlx/", "vllm_mlx/")):
+        local = True
+        signals.append("explicit_local_route")
+    if local:
+        signals.append("local_model")
+        return WorkIntent("local_model", "serve_endpoint", True, "local_runtime", 0.92, tuple(signals))
+
+    if _has_any(text, ("security", "audit", "vulnerability", "보안", "취약점", "시크릿")):
+        signals.append("security")
+        return WorkIntent("security", "review_risk", False, "host_managed", 0.86, tuple(signals))
+
+    if _has_any(text, ("test", "pytest", "unit", "테스트", "검증")):
+        signals.append("test")
+        return WorkIntent("engineering", "verify_or_fix", False, _direction_for_surface(item.surface), 0.82, tuple(signals))
+
+    if _has_any(text, ("code", "implement", "fix", "refactor", "패치", "수정", "구현", "리팩터")):
+        signals.append("coding")
+        return WorkIntent("engineering", "code_change", False, _direction_for_surface(item.surface), 0.80, tuple(signals))
+
+    if _has_any(text, ("docs", "readme", "문서", "가이드", "사용법")):
+        signals.append("documentation")
+        return WorkIntent("documentation", "write_or_update_docs", False, "host_managed", 0.78, tuple(signals))
+
+    return WorkIntent("general", "plan_task", False, _direction_for_surface(item.surface), 0.55, tuple(signals))
+
+
+def _direction_for_surface(surface: AgentSurface) -> str:
+    if surface == AgentSurface.HERMES:
+        return "hermes_harness"
+    if surface == AgentSurface.CODEX:
+        return "codex_harness"
+    if surface == AgentSurface.CLAUDE:
+        return "claude_harness"
+    if surface == AgentSurface.GROK_BUILD:
+        return "grok_build_harness"
+    return "host_managed"
+
+
+def _has_any(text: str, needles: tuple[str, ...]) -> bool:
+    return any(needle in text for needle in needles)
+
+
+__all__ = ["classify_intent"]

cluxion_runtime/core/ledger.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+"""작업큐 상태를 JSONL 이벤트로 남기는 durable ledger."""
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from cluxion_runtime.core.ledger_codec import item_from_dict, item_to_dict
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from cluxion_runtime.core.types import WorkItem
+
+
+class WorkStatus(StrEnum):
+    """작업 ledger의 닫힌 상태 집합."""
+
+    QUEUED = "queued"
+    RUNNING = "running"
+    RETRY_WAIT = "retry_wait"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    DEAD = "dead"
+
+
+@dataclass(frozen=True)
+class RetryDecision:
+    """실패 후 재시도 가능 여부."""
+
+    retryable: bool
+    next_after_epoch: float
+    attempt: int
+    reason: str
+
+
+@dataclass(frozen=True)
+class LedgerEntry:
+    """특정 work_id의 최신 ledger 상태."""
+
+    work_id: str
+    status: WorkStatus
+    attempt: int
+    max_attempts: int
+    next_after_epoch: float
+    reason: str
+    item: WorkItem
+
+
+class LedgerCorruptionError(RuntimeError):
+    """ledger JSONL이 손상됐을 때 조용한 통과를 막는 오류."""
+
+
+class DurableWorkLedger:
+    """프로세스 재시작 후에도 작업 상태를 복원하는 JSONL ledger."""
+
+    def __init__(self, path: Path, *, sync_on_write: bool = True) -> None:
+        self._path = path
+        self._sync_on_write = sync_on_write
+
+    def record_enqueued(self, item: WorkItem, *, max_attempts: int = 3) -> LedgerEntry:
+        """신규 작업을 durable queue에 등록한다."""
+        event = self._event(item, WorkStatus.QUEUED, attempt=0, max_attempts=max_attempts, reason="queued")
+        self._append(event)
+        return self._entry_from_event(event)
+
+    def record_started(self, work_id: str, *, now: float | None = None) -> LedgerEntry:
+        """실행 시작 이벤트를 기록한다."""
+        entry = self.latest()[work_id]
+        event = self._event(
+            entry.item,
+            WorkStatus.RUNNING,
+            attempt=entry.attempt + 1,
+            max_attempts=entry.max_attempts,
+            reason="started",
+            now=now,
+        )
+        self._append(event)
+        return self._entry_from_event(event)
+
+    def record_finished(self, work_id: str, *, reason: str = "succeeded") -> LedgerEntry:
+        """성공 종료 이벤트를 기록한다."""
+        entry = self.latest()[work_id]
+        event = self._event(entry.item, WorkStatus.SUCCEEDED, attempt=entry.attempt, max_attempts=entry.max_attempts, reason=reason)
+        self._append(event)
+        return self._entry_from_event(event)
+
+    def record_failed(
+        self,
+        work_id: str,
+        *,
+        reason: str,
+        retryable: bool = True,
+        backoff_base_sec: float = 1.0,
+        now: float | None = None,
+    ) -> RetryDecision:
+        """실패 이벤트와 재시도 대기 또는 dead 상태를 기록한다."""
+        current = time.time() if now is None else now
+        entry = self.latest()[work_id]
+        can_retry = retryable and entry.attempt < entry.max_attempts
+        delay = backoff_base_sec * (2 ** max(0, entry.attempt - 1))
+        status = WorkStatus.RETRY_WAIT if can_retry else WorkStatus.DEAD
+        next_after = current + delay if can_retry else 0.0
+        event = self._event(
+            entry.item,
+            status,
+            attempt=entry.attempt,
+            max_attempts=entry.max_attempts,
+            next_after_epoch=next_after,
+            reason=reason,
+            now=current,
+        )
+        self._append(event)
+        return RetryDecision(can_retry, next_after, entry.attempt, reason)
+
+    def latest(self) -> dict[str, LedgerEntry]:
+        """JSONL 전체를 접어서 work_id별 최신 상태를 반환한다."""
+        states: dict[str, LedgerEntry] = {}
+        if not self._path.exists():
+            return states
+        for number, line in enumerate(self._path.read_text(encoding="utf-8").splitlines(), start=1):
+            if not line.strip():
+                continue
+            try:
+                event = json.loads(line)
+                entry = self._entry_from_event(event)
+            except (json.JSONDecodeError, KeyError, TypeError, ValueError) as exc:
+                raise LedgerCorruptionError(f"ledger line {number} is invalid: {exc}") from exc
+            states[entry.work_id] = entry
+        return states
+
+    def ready_to_retry(self, *, now: float | None = None) -> tuple[LedgerEntry, ...]:
+        """재시도 시간이 도래한 작업만 우선순위 순서로 반환한다."""
+        current = time.time() if now is None else now
+        ready = [
+            entry
+            for entry in self.latest().values()
+            if entry.status == WorkStatus.RETRY_WAIT and entry.next_after_epoch <= current
+        ]
+        return tuple(sorted(ready, key=lambda entry: (int(entry.item.priority), entry.work_id)))
+
+    def _append(self, event: dict[str, object]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(event, ensure_ascii=False, sort_keys=True)
+        with self._path.open("a", encoding="utf-8") as handle:
+            handle.write(payload + "\n")
+            if self._sync_on_write:
+                handle.flush()
+                os.fsync(handle.fileno())
+
+    def _event(
+        self,
+        item: WorkItem,
+        status: WorkStatus,
+        *,
+        attempt: int,
+        max_attempts: int,
+        reason: str,
+        next_after_epoch: float = 0.0,
+        now: float | None = None,
+    ) -> dict[str, object]:
+        return {
+            "created_at": time.time() if now is None else now,
+            "work_id": item.work_id,
+            "status": status.value,
+            "attempt": max(0, attempt),
+            "max_attempts": max(1, max_attempts),
+            "next_after_epoch": max(0.0, next_after_epoch),
+            "reason": reason,
+            "item": item_to_dict(item),
+        }
+
+    def _entry_from_event(self, event: dict[str, object]) -> LedgerEntry:
+        return LedgerEntry(
+            work_id=str(event["work_id"]),
+            status=WorkStatus(str(event["status"])),
+            attempt=int(event["attempt"]),
+            max_attempts=int(event["max_attempts"]),
+            next_after_epoch=float(event["next_after_epoch"]),
+            reason=str(event["reason"]),
+            item=item_from_dict(event["item"]),
+        )
+
+
+__all__ = ["DurableWorkLedger", "LedgerCorruptionError", "LedgerEntry", "RetryDecision", "WorkStatus"]

cluxion_runtime/core/ledger_codec.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+"""durable ledger가 쓰는 WorkItem 직렬화 코덱."""
+
+from cluxion_runtime.core.types import AgentSurface, WorkItem, WorkPriority
+
+
+def item_to_dict(item: WorkItem) -> dict[str, object]:
+    """WorkItem을 JSON 안전 객체로 바꾼다."""
+    return {
+        "work_id": item.work_id,
+        "prompt": item.prompt,
+        "surface": item.surface.value,
+        "priority": int(item.priority),
+        "model_route": item.model_route,
+        "expected_ram_mb": item.expected_ram_mb,
+        "context_tokens": item.context_tokens,
+        "metadata": dict(item.metadata),
+    }
+
+
+def item_from_dict(payload: object) -> WorkItem:
+    """JSON 객체에서 WorkItem을 복원한다."""
+    if not isinstance(payload, dict):
+        raise TypeError("item payload must be an object")
+    return WorkItem(
+        work_id=str(payload["work_id"]),
+        prompt=str(payload["prompt"]),
+        surface=AgentSurface(str(payload["surface"])),
+        priority=WorkPriority(int(payload["priority"])),
+        model_route=str(payload["model_route"]),
+        expected_ram_mb=int(payload["expected_ram_mb"]),
+        context_tokens=int(payload["context_tokens"]),
+        metadata={str(key): str(value) for key, value in dict(payload["metadata"]).items()},
+    )
+
+
+__all__ = ["item_from_dict", "item_to_dict"]