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

cluxion_runtime/core/types.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+"""새 Cluxion 런타임의 작은 데이터 계약."""
+
+from dataclasses import dataclass, field
+from enum import IntEnum, StrEnum
+
+
+class AgentSurface(StrEnum):
+    """Cluxion 앞단에 붙는 에이전트 표면."""
+
+    HERMES = "hermes"
+    CODEX = "codex"
+    CLAUDE = "claude"
+    GROK_BUILD = "grok_build"
+    LOCAL = "local"
+    API = "api"
+
+
+class RuntimeKind(StrEnum):
+    """실제 모델 실행 백엔드."""
+
+    HOST_MANAGED = "host_managed"
+    VLLM_MLX = "vllm_mlx"
+    MLX_LM = "mlx_lm"
+    OLLAMA = "ollama"
+    OPENAI_COMPAT = "openai_compat"
+    GENERIC = "generic"
+
+
+class WorkPriority(IntEnum):
+    """작업큐 우선순위. 숫자가 작을수록 먼저 실행된다."""
+
+    CRITICAL = 0
+    HIGH = 1
+    NORMAL = 2
+    LOW = 3
+
+
+@dataclass(frozen=True)
+class WorkItem:
+    """외부 에이전트에서 Cluxion으로 들어온 단일 작업."""
+
+    work_id: str
+    prompt: str
+    surface: AgentSurface = AgentSurface.API
+    priority: WorkPriority = WorkPriority.NORMAL
+    model_route: str = "host/default"
+    expected_ram_mb: int = 0
+    context_tokens: int = 0
+    metadata: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class QueueSegment:
+    """장문 작업을 실행 가능한 단위로 쪼갠 세그먼트."""
+
+    segment_id: str
+    char_start: int
+    char_end: int
+    token_estimate: int
+    checksum: str
+    preview: str
+    content: str
+
+
+@dataclass(frozen=True)
+class AnswerPolicy:
+    """Host agent가 모델 호출 전 지켜야 하는 응답 안전 계약."""
+
+    unknown_behavior: str = "say_unknown_if_insufficient_context"
+    source_policy: str = "do_not_invent_sources_or_facts"
+    scope: str = "answer_only_from_available_context_and_verified_runtime_state"
+    response_contract: str = "direct_answer_with_uncertainty_boundary"
+    verification_required: bool = False
+    citation_required: bool = False
+    uncertainty_level: str = "low"
+    required_checks: tuple[str, ...] = ()
+    grounding: tuple[str, ...] = (
+        "verified_facts",
+        "explicit_user_context",
+        "tool_results",
+        "clearly_labeled_inferences",
+    )
+    rules: tuple[str, ...] = (
+        "If the available context is insufficient, say that clearly before proceeding.",
+        "Do not fabricate file state, external facts, tool results, or model availability.",
+        "For current or environment-specific claims, verify through tools before presenting them as facts.",
+        "Separate verified facts from inferences and unknowns when accuracy matters.",
+        "If a check was not run, say it was not run; do not imply that it passed.",
+    )
+
+
+@dataclass(frozen=True)
+class PreprocessResult:
+    """모델 호출 전 결정론 전처리 결과."""
+
+    normalized_prompt: str
+    segments: tuple[QueueSegment, ...]
+    token_estimate: int
+    split_required: bool
+    effort: str
+    evidence: tuple[str, ...]
+    mode: str = "standard"
+    preprocess_required: bool = True
+    reason_codes: tuple[str, ...] = ()
+    answer_policy: AnswerPolicy = field(default_factory=AnswerPolicy)
+
+
+@dataclass(frozen=True)
+class WorkIntent:
+    """Deterministic user intent and routing direction."""
+
+    category: str
+    operation: str
+    local_model_requested: bool
+    direction: str
+    confidence: float
+    signals: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ResourceSnapshot:
+    """Rust 또는 Python fallback으로 얻은 리소스 스냅샷."""
+
+    total_ram_mb: int
+    available_ram_mb: int
+    swap_used_mb: int
+    cpu_percent: float
+    zombie_pids: tuple[int, ...] = ()
+
+
+@dataclass(frozen=True)
+class ResourceDecision:
+    """실행 admission 판정 결과."""
+
+    allowed: bool
+    mode: str
+    reason: str
+    recommended_parallel: int
+    work_kind: str
+    dispatch_memory_budget_mb: int
+    reason_codes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ModelRuntimeProfile:
+    """로컬 모델 서버 실행 프로필."""
+
+    kind: RuntimeKind
+    model: str
+    base_url: str
+    command: tuple[str, ...]
+    health_path: str = "/v1/models"
+
+
+@dataclass(frozen=True)
+class HostExecutionStep:
+    """Hermes의 현재 모델이 수행해야 하는 host-owned 실행 단계."""
+
+    step_id: str
+    kind: str
+    prompt: str
+    segment_id: str = ""
+    checksum: str = ""
+    token_estimate: int = 0
+    depends_on: tuple[str, ...] = ()
+    required_checks: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class HostExecutionPlan:
+    """Cluxion이 모델을 직접 호출하지 않고 host 모델 사용법만 지정하는 계약."""
+
+    model_owner: str
+    provider_policy: str
+    strategy: str
+    queue_required: bool
+    synthesis_required: bool
+    preflight_required: bool
+    max_extra_model_calls: int
+    steps: tuple[HostExecutionStep, ...]
+    next_tool: str = ""
+    record_tool: str = ""
+    brief_tool: str = ""
+    performance_notes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class HarnessPlan:
+    """에이전트 표면이 Cluxion에 넘긴 작업의 실행 계획."""
+
+    item: WorkItem
+    intent: WorkIntent
+    preprocessing: PreprocessResult
+    resource: ResourceDecision
+    runtime: ModelRuntimeProfile
+    execution: HostExecutionPlan
+    queue_position: int = 0
+    clarification_required: bool = False
+    clarification_questions: tuple[str, ...] = ()
+    queue_backend: str = "python"
+
+
+__all__ = [
+    "AgentSurface",
+    "AnswerPolicy",
+    "HarnessPlan",
+    "HostExecutionPlan",
+    "HostExecutionStep",
+    "ModelRuntimeProfile",
+    "PreprocessResult",
+    "QueueSegment",
+    "ResourceDecision",
+    "ResourceSnapshot",
+    "RuntimeKind",
+    "WorkIntent",
+    "WorkItem",
+    "WorkPriority",
+]

cluxion_runtime/core/work_queue.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+"""우선순위 기반 Agent 작업큐."""
+
+import heapq
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cluxion_runtime.core.types import WorkItem
+
+
+@dataclass(frozen=True)
+class QueueAdmission:
+    """작업큐 삽입 결과."""
+
+    accepted: bool
+    reason: str
+    evicted_work_id: str = ""
+
+
+@dataclass(order=True)
+class _QueueEntry:
+    priority: int
+    sequence: int
+    item: WorkItem = field(compare=False)
+
+
+class AgentWorkQueue:
+    """작업 중요도와 FIFO를 함께 지키는 작은 큐."""
+
+    def __init__(self, max_size: int = 256) -> None:
+        if max_size < 1:
+            raise ValueError("max_size는 1 이상이어야 한다.")
+        self._max_size = max_size
+        self._sequence = 0
+        self._heap: list[_QueueEntry] = []
+
+    def enqueue(self, item: WorkItem) -> QueueAdmission:
+        """용량이 차면 낮은 우선순위 작업만 밀어낸다."""
+        entry = _QueueEntry(int(item.priority), self._sequence, item)
+        self._sequence += 1
+        if len(self._heap) < self._max_size:
+            heapq.heappush(self._heap, entry)
+            return QueueAdmission(True, "queued")
+        worst_index = self._worst_index()
+        worst = self._heap[worst_index]
+        if entry.priority >= worst.priority:
+            return QueueAdmission(False, "queue_full_lower_or_equal_priority")
+        evicted = worst.item.work_id
+        self._heap[worst_index] = entry
+        heapq.heapify(self._heap)
+        return QueueAdmission(True, "queued_after_eviction", evicted)
+
+    def dequeue(self) -> WorkItem | None:
+        """가장 높은 우선순위의 작업을 꺼낸다."""
+        if not self._heap:
+            return None
+        return heapq.heappop(self._heap).item
+
+    def peek_order(self) -> tuple[str, ...]:
+        """실행 예정 순서를 작업 ID로 반환한다."""
+        return tuple(entry.item.work_id for entry in sorted(self._heap))
+
+    def size(self) -> int:
+        """현재 대기 작업 수를 반환한다."""
+        return len(self._heap)
+
+    def _worst_index(self) -> int:
+        return max(range(len(self._heap)), key=lambda index: (self._heap[index].priority, self._heap[index].sequence))
+
+
+__all__ = ["AgentWorkQueue", "QueueAdmission"]

cluxion_runtime/models/__init__.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+"""로컬 모델 런타임 프로필."""
+
+from cluxion_runtime.models.supervisor import LocalModelSupervisor, ModelServerHealth, SupervisorStartResult
+from cluxion_runtime.models.vllm_mlx import VllmMlxProfile, build_vllm_mlx_profile, select_mac_local_profile
+
+__all__ = [
+    "LocalModelSupervisor",
+    "ModelServerHealth",
+    "SupervisorStartResult",
+    "VllmMlxProfile",
+    "build_vllm_mlx_profile",
+    "select_mac_local_profile",
+]

cluxion_runtime/models/supervisor.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+"""로컬 모델 서버 프로세스와 health check를 관리하는 supervisor."""
+
+import json
+import os
+import subprocess
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol
+from urllib.request import urlopen
+
+if TYPE_CHECKING:
+    from cluxion_runtime.core.types import ModelRuntimeProfile
+
+
+class ManagedProcess(Protocol):
+    """subprocess.Popen이 제공해야 하는 최소 프로세스 계약."""
+
+    pid: int
+
+    def poll(self) -> int | None: ...
+
+    def terminate(self) -> None: ...
+
+    def wait(self, timeout: float | None = None) -> int: ...
+
+    def kill(self) -> None: ...
+
+
+ProcessFactory = Callable[[tuple[str, ...], Path | None, Mapping[str, str] | None], ManagedProcess]
+HealthGetter = Callable[[str, float], tuple[int, str]]
+
+
+@dataclass(frozen=True)
+class SupervisorStartResult:
+    """모델 서버 시작 결과."""
+
+    started: bool
+    pid: int
+    reason: str
+
+
+@dataclass(frozen=True)
+class ModelServerHealth:
+    """OpenAI-compatible 모델 서버 health 결과."""
+
+    reachable: bool
+    status_code: int
+    reason: str
+    models: tuple[str, ...] = ()
+
+
+class LocalModelSupervisor:
+    """vLLM-MLX 같은 로컬 모델 서버의 생명주기를 관리한다."""
+
+    def __init__(
+        self,
+        profile: ModelRuntimeProfile,
+        *,
+        cwd: Path | None = None,
+        env: Mapping[str, str] | None = None,
+        process_factory: ProcessFactory | None = None,
+        health_getter: HealthGetter | None = None,
+    ) -> None:
+        self._profile = profile
+        self._cwd = cwd
+        self._env = env
+        self._process_factory = _spawn_process if process_factory is None else process_factory
+        self._health_getter = _default_health_get if health_getter is None else health_getter
+        self._process: ManagedProcess | None = None
+
+    @property
+    def profile(self) -> ModelRuntimeProfile:
+        """감시 대상 런타임 프로필을 반환한다."""
+        return self._profile
+
+    def start(self) -> SupervisorStartResult:
+        """프로세스가 없으면 모델 서버를 시작한다."""
+        if self.is_running():
+            pid = 0 if self._process is None else self._process.pid
+            return SupervisorStartResult(False, pid, "already_running")
+        if not self._profile.command:
+            return SupervisorStartResult(False, 0, "empty_command")
+        self._process = self._process_factory(self._profile.command, self._cwd, self._env)
+        return SupervisorStartResult(True, self._process.pid, "started")
+
+    def is_running(self) -> bool:
+        """프로세스가 살아 있으면 true를 반환한다."""
+        return self._process is not None and self._process.poll() is None
+
+    def stop(self, *, timeout_sec: float = 5.0) -> bool:
+        """정상 종료를 시도하고, 시간 초과 시 강제 종료한다."""
+        if self._process is None:
+            return False
+        process = self._process
+        if process.poll() is None:
+            process.terminate()
+            try:
+                process.wait(timeout=timeout_sec)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait(timeout=timeout_sec)
+        self._process = None
+        return True
+
+    def health_check(self, *, timeout_sec: float = 1.0) -> ModelServerHealth:
+        """OpenAI-compatible `/v1/models` 응답을 점검한다."""
+        url = _health_url(self._profile)
+        try:
+            status, body = self._health_getter(url, timeout_sec)
+            models = _parse_models(body)
+            return ModelServerHealth(status < 500, status, "ok" if status < 500 else "server_error", models)
+        except (OSError, TimeoutError, ValueError, json.JSONDecodeError) as exc:
+            return ModelServerHealth(False, 0, f"health_check_failed:{exc}")
+
+
+def _spawn_process(command: tuple[str, ...], cwd: Path | None, env: Mapping[str, str] | None) -> ManagedProcess:
+    child_env = None if env is None else {**os.environ, **dict(env)}
+    return subprocess.Popen(
+        command,
+        cwd=cwd,
+        env=child_env,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+
+
+def _default_health_get(url: str, timeout_sec: float) -> tuple[int, str]:
+    with urlopen(url, timeout=timeout_sec) as response:
+        return int(response.status), response.read().decode("utf-8")
+
+
+def _health_url(profile: ModelRuntimeProfile) -> str:
+    base = profile.base_url.rstrip("/")
+    path = profile.health_path
+    if base.endswith("/v1") and path.startswith("/v1/"):
+        path = path.removeprefix("/v1")
+    return base + path
+
+
+def _parse_models(body: str) -> tuple[str, ...]:
+    payload = json.loads(body)
+    if not isinstance(payload, dict):
+        return ()
+    data = payload.get("data")
+    if not isinstance(data, list):
+        return ()
+    ids = [item.get("id") for item in data if isinstance(item, dict)]
+    return tuple(str(model_id) for model_id in ids if model_id)
+
+
+__all__ = ["LocalModelSupervisor", "ManagedProcess", "ModelServerHealth", "SupervisorStartResult"]

cluxion_runtime/models/vllm_mlx.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+"""Apple Silicon용 vLLM-MLX 실행 프로필."""
+
+import platform
+from dataclasses import dataclass
+
+from cluxion_runtime.core.types import ModelRuntimeProfile, RuntimeKind
+
+
+@dataclass(frozen=True)
+class VllmMlxProfile:
+    """vLLM-MLX OpenAI-compatible server 실행 옵션."""
+
+    model: str
+    host: str = "127.0.0.1"
+    port: int = 8000
+    max_tokens: int = 128_000
+    continuous_batching: bool = True
+    prefix_cache: bool = True
+    executable: str = "vllm-mlx"
+
+    @property
+    def base_url(self) -> str:
+        """OpenAI-compatible base URL."""
+        return f"http://{self.host}:{self.port}/v1"
+
+    def command(self) -> tuple[str, ...]:
+        """vLLM-MLX 서버 시작 명령을 만든다."""
+        cmd = [
+            self.executable,
+            "serve",
+            self.model,
+            "--host",
+            self.host,
+            "--port",
+            str(self.port),
+            "--max-tokens",
+            str(self.max_tokens),
+        ]
+        if self.continuous_batching:
+            cmd.append("--continuous-batching")
+        if self.prefix_cache:
+            cmd.append("--enable-prefix-cache")
+        return tuple(cmd)
+
+    def runtime_profile(self) -> ModelRuntimeProfile:
+        """공통 하네스가 쓰는 모델 실행 프로필로 변환한다."""
+        return ModelRuntimeProfile(
+            kind=RuntimeKind.VLLM_MLX,
+            model=self.model,
+            base_url=self.base_url,
+            command=self.command(),
+        )
+
+
+def build_vllm_mlx_profile(
+    model: str,
+    *,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    max_tokens: int = 128_000,
+    executable: str = "vllm-mlx",
+) -> ModelRuntimeProfile:
+    """명시 모델 ID로 vLLM-MLX 프로필을 만든다."""
+    return VllmMlxProfile(
+        model=model,
+        host=host,
+        port=port,
+        max_tokens=max_tokens,
+        executable=executable,
+    ).runtime_profile()
+
+
+def select_mac_local_profile(model: str, *, port: int = 8000) -> ModelRuntimeProfile:
+    """Mac Apple Silicon이면 vLLM-MLX를 우선 선택하고, 그 외에는 일반 OpenAI endpoint로 둔다."""
+    if platform.system() == "Darwin" and platform.machine().lower() in {"arm64", "aarch64"}:
+        return build_vllm_mlx_profile(model, port=port)
+    return ModelRuntimeProfile(
+        kind=RuntimeKind.OPENAI_COMPAT,
+        model=model,
+        base_url=f"http://127.0.0.1:{port}/v1",
+        command=("vllm", "serve", model, "--host", "127.0.0.1", "--port", str(port)),
+    )
+
+
+__all__ = ["VllmMlxProfile", "build_vllm_mlx_profile", "select_mac_local_profile"]

cluxion_runtime/resources/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+"""Rust 자원 판정 브리지."""
+
+from cluxion_runtime.resources.rust_bridge import capacity_decision, collect_resource_snapshot, evaluate_pressure
+
+__all__ = ["capacity_decision", "collect_resource_snapshot", "evaluate_pressure"]

cluxion_runtime/resources/queue_bridge.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+"""Rust-backed durable queue with Python fallback."""
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+QUEUE_BIN_ENV = "CLUXION_QUEUE_BIN"
+QUEUE_STORE_ENV = "CLUXION_QUEUE_STORE_DIR"
+_DEFAULT_STORE = Path.home() / ".local" / "share" / "cluxion-agentplugin-preprocessing" / "queue"
+
+
+def queue_available() -> bool:
+    """Return True when the Rust queue binary is callable."""
+    return shutil.which(_queue_binary()) is not None
+
+
+def default_store_dir() -> Path:
+    return Path(os.environ.get(QUEUE_STORE_ENV, str(_DEFAULT_STORE))).expanduser()
+
+
+def enqueue_work(payload: Mapping[str, object], *, store_dir: Path | None = None) -> dict[str, object]:
+    """Enqueue work via Rust when available, else raise for Python fallback."""
+    return _invoke("enqueue", payload, store_dir=store_dir)
+
+
+def dequeue_work(*, store_dir: Path | None = None) -> dict[str, object]:
+    return _invoke("dequeue", {}, store_dir=store_dir)
+
+
+def peek_order(*, store_dir: Path | None = None, limit: int = 16) -> dict[str, object]:
+    return _invoke("peek", {"limit": limit}, store_dir=store_dir)
+
+
+def persist_dispatch_bundle(work_id: str, bundle: Mapping[str, object], *, store_dir: Path | None = None) -> dict[str, object]:
+    return _invoke(
+        "persist",
+        {"work_id": work_id, "bundle": dict(bundle)},
+        store_dir=store_dir,
+    )
+
+
+def next_dispatch_step(work_id: str, *, store_dir: Path | None = None) -> dict[str, object]:
+    return _invoke("next", {"work_id": work_id}, store_dir=store_dir)
+
+
+def record_dispatch_step(
+    work_id: str,
+    step_id: str,
+    *,
+    result: str = "",
+    error: str = "",
+    failed: bool = False,
+    store_dir: Path | None = None,
+) -> dict[str, object]:
+    return _invoke(
+        "record",
+        {
+            "work_id": work_id,
+            "step_id": step_id,
+            "result": result,
+            "error": error,
+            "failed": failed,
+        },
+        store_dir=store_dir,
+    )
+
+
+def build_briefing(work_id: str, *, store_dir: Path | None = None) -> dict[str, object]:
+    return _invoke("brief", {"work_id": work_id}, store_dir=store_dir)
+
+
+def queue_status(*, store_dir: Path | None = None) -> dict[str, object]:
+    return _invoke("status", {}, store_dir=store_dir)
+
+
+def _invoke(command: str, payload: Mapping[str, object], *, store_dir: Path | None) -> dict[str, object]:
+    binary = _queue_binary()
+    if shutil.which(binary) is None:
+        raise RuntimeError("cluxion-queue binary not found")
+    body = dict(payload)
+    body["store_dir"] = str(default_store_dir() if store_dir is None else store_dir)
+    completed = subprocess.run(
+        [binary, command],
+        input=json.dumps(body, ensure_ascii=False),
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if completed.returncode != 0:
+        raise RuntimeError(completed.stderr.strip() or f"cluxion-queue {command} failed")
+    parsed = json.loads(completed.stdout)
+    if not isinstance(parsed, dict):
+        raise RuntimeError(f"cluxion-queue {command} returned non-object JSON")
+    return parsed
+
+
+def _queue_binary() -> str:
+    configured = os.environ.get(QUEUE_BIN_ENV, "").strip()
+    if configured:
+        return configured
+    local = Path(__file__).resolve().parents[3] / "rust" / "cluxion_queue" / "target" / "release" / "cluxion-queue"
+    if local.exists():
+        return str(local)
+    return "cluxion-queue"
+
+
+__all__ = [
+    "QUEUE_BIN_ENV",
+    "QUEUE_STORE_ENV",
+    "build_briefing",
+    "default_store_dir",
+    "dequeue_work",
+    "enqueue_work",
+    "next_dispatch_step",
+    "peek_order",
+    "persist_dispatch_bundle",
+    "queue_available",
+    "queue_status",
+    "record_dispatch_step",
+]