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

cluxion_runtime/bootstrap.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+"""Runtime dependency bootstrap for local model backends."""
+
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable, Sequence
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+
+LOCAL_RUNTIME_PACKAGES: tuple[str, ...] = ("vllm-mlx",)
+LOCAL_RUNTIME_COMMANDS: tuple[str, ...] = ("vllm-mlx",)
+RUNTIME_VENV_ENV = "CLUXION_PREPROCESS_RUNTIME_VENV"
+RUNTIME_HOME_ENV = "CLUXION_PREPROCESS_RUNTIME_HOME"
+_LEGACY_RUNTIME_VENV_ENV = "HERMES_CLUXION_RUNTIME_VENV"
+_LEGACY_RUNTIME_HOME_ENV = "HERMES_CLUXION_RUNTIME_HOME"
+
+
+@dataclass(frozen=True)
+class BootstrapResult:
+    """Dependency bootstrap result."""
+
+    ok: bool
+    changed: bool
+    packages: tuple[str, ...]
+    commands: tuple[str, ...]
+    install_command: tuple[str, ...]
+    runtime_dir: str = ""
+    command_paths: dict[str, str] | None = None
+    setup_command: tuple[str, ...] = ()
+    returncode: int = 0
+    stdout: str = ""
+    stderr: str = ""
+    reason: str = ""
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "ok": self.ok,
+            "changed": self.changed,
+            "packages": list(self.packages),
+            "commands": list(self.commands),
+            "install_command": list(self.install_command),
+            "runtime_dir": self.runtime_dir,
+            "command_paths": dict(self.command_paths or {}),
+            "setup_command": list(self.setup_command),
+            "returncode": self.returncode,
+            "stdout": self.stdout[-4_000:],
+            "stderr": self.stderr[-4_000:],
+            "reason": self.reason,
+        }
+
+
+CommandRunner = Callable[[Sequence[str], float], subprocess.CompletedProcess[str]]
+
+
+def ensure_local_runtime(
+    *,
+    packages: Sequence[str] = LOCAL_RUNTIME_PACKAGES,
+    commands: Sequence[str] = LOCAL_RUNTIME_COMMANDS,
+    upgrade: bool = False,
+    dry_run: bool = False,
+    python: str | None = None,
+    runtime_dir: str | Path | None = None,
+    timeout_sec: float = 900.0,
+    command_runner: CommandRunner | None = None,
+) -> BootstrapResult:
+    """Install or upgrade packages required by the local model runtime."""
+    package_tuple = tuple(_validate_package_name(package) for package in packages)
+    command_tuple = tuple(commands)
+    runtime_path = _runtime_dir(runtime_dir)
+    runtime_python = Path(python) if python else _runtime_python(runtime_path)
+    command_paths = _command_paths(command_tuple, runtime_python)
+    missing = tuple(command for command, path in command_paths.items() if not Path(path).exists())
+    setup_command = _setup_command(runtime_path) if not python and not runtime_python.exists() else ()
+    install_command = _install_command(package_tuple, upgrade=upgrade, python=str(runtime_python))
+    if not missing and not upgrade:
+        return BootstrapResult(
+            True,
+            False,
+            package_tuple,
+            command_tuple,
+            install_command,
+            str(runtime_path),
+            command_paths,
+            setup_command,
+            reason="already_available",
+        )
+    if dry_run:
+        reason = "upgrade_requested" if upgrade else f"missing_commands:{','.join(missing)}"
+        return BootstrapResult(
+            True,
+            False,
+            package_tuple,
+            command_tuple,
+            install_command,
+            str(runtime_path),
+            command_paths,
+            setup_command,
+            reason=reason,
+        )
+    runner = _run_command if command_runner is None else command_runner
+    try:
+        setup_completed = _completed_ok(setup_command)
+        if setup_command:
+            setup_completed = runner(setup_command, timeout_sec)
+        if setup_completed.returncode != 0:
+            return BootstrapResult(
+                False,
+                False,
+                package_tuple,
+                command_tuple,
+                install_command,
+                str(runtime_path),
+                command_paths,
+                setup_command,
+                setup_completed.returncode,
+                setup_completed.stdout,
+                setup_completed.stderr,
+                "runtime_venv_failed",
+            )
+        completed = runner(install_command, timeout_sec)
+    except OSError as exc:
+        return BootstrapResult(
+            False,
+            False,
+            package_tuple,
+            command_tuple,
+            install_command,
+            str(runtime_path),
+            command_paths,
+            setup_command,
+            1,
+            "",
+            str(exc),
+            "install_failed",
+        )
+    ok = completed.returncode == 0 and all(Path(path).exists() for path in command_paths.values())
+    reason = "installed" if ok and missing else "upgraded" if ok else "install_failed"
+    return BootstrapResult(
+        ok,
+        completed.returncode == 0,
+        package_tuple,
+        command_tuple,
+        install_command,
+        str(runtime_path),
+        command_paths,
+        setup_command,
+        completed.returncode,
+        _join_output(setup_completed.stdout, completed.stdout),
+        _join_output(setup_completed.stderr, completed.stderr),
+        reason,
+    )
+
+
+def _runtime_dir(runtime_dir: str | Path | None) -> Path:
+    if runtime_dir is not None:
+        return Path(runtime_dir).expanduser()
+    for env_name in (RUNTIME_VENV_ENV, _LEGACY_RUNTIME_VENV_ENV):
+        env_venv = os_environ(env_name)
+        if env_venv:
+            return Path(env_venv).expanduser()
+    home_value = ""
+    for env_name in (RUNTIME_HOME_ENV, _LEGACY_RUNTIME_HOME_ENV):
+        home_value = os_environ(env_name)
+        if home_value:
+            break
+    home = Path(home_value or Path.home() / ".local" / "share" / "cluxion-agentplugin-preprocessing")
+    return home.expanduser() / "runtime-venv"
+
+
+def _runtime_python(runtime_dir: Path) -> Path:
+    return _bin_dir(runtime_dir) / ("python.exe" if sys.platform == "win32" else "python")
+
+
+def _bin_dir(runtime_dir: Path) -> Path:
+    return runtime_dir / ("Scripts" if sys.platform == "win32" else "bin")
+
+
+def _command_paths(commands: tuple[str, ...], runtime_python: Path) -> dict[str, str]:
+    return {command: str(runtime_python.parent / command) for command in commands}
+
+
+def _setup_command(runtime_dir: Path) -> tuple[str, ...]:
+    uv = shutil.which("uv")
+    if uv is not None:
+        return (uv, "venv", "--seed", str(runtime_dir))
+    return (sys.executable, "-m", "venv", str(runtime_dir))
+
+
+def _install_command(packages: tuple[str, ...], *, upgrade: bool, python: str | None) -> tuple[str, ...]:
+    python_executable = python or sys.executable
+    if _python_module_available(python_executable, "pip"):
+        command = [python_executable, "-m", "pip", "install", "--disable-pip-version-check"]
+        if upgrade:
+            command.append("--upgrade")
+        command.extend(packages)
+        return tuple(command)
+
+    uv = shutil.which("uv")
+    if uv is not None:
+        command = [uv, "pip", "install", "--python", python_executable]
+        if upgrade:
+            command.append("--upgrade")
+        command.extend(packages)
+        return tuple(command)
+
+    command = [python_executable, "-m", "pip", "install", "--disable-pip-version-check"]
+    if upgrade:
+        command.append("--upgrade")
+    command.extend(packages)
+    return tuple(command)
+
+
+def _python_module_available(python: str, module: str) -> bool:
+    with suppress(OSError, subprocess.TimeoutExpired):
+        completed = subprocess.run(
+            [python, "-m", module, "--version"],
+            text=True,
+            capture_output=True,
+            check=False,
+            timeout=10,
+        )
+        return completed.returncode == 0
+    return False
+
+
+def _run_command(command: Sequence[str], timeout_sec: float) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        list(command),
+        text=True,
+        capture_output=True,
+        check=False,
+        timeout=timeout_sec,
+    )
+
+
+def _completed_ok(command: Sequence[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.CompletedProcess(list(command), 0, stdout="", stderr="")
+
+
+def _join_output(*parts: str) -> str:
+    return "\n".join(part for part in parts if part)
+
+
+def os_environ(key: str) -> str | None:
+    import os
+
+    return os.environ.get(key)
+
+
+def _validate_package_name(package: str) -> str:
+    cleaned = package.strip()
+    if not cleaned:
+        raise ValueError("package name must not be empty")
+    allowed = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-<>=!~")
+    if any(ch not in allowed for ch in cleaned):
+        raise ValueError(f"unsafe package specifier: {package!r}")
+    return cleaned
+
+
+__all__ = [
+    "LOCAL_RUNTIME_COMMANDS",
+    "LOCAL_RUNTIME_PACKAGES",
+    "RUNTIME_HOME_ENV",
+    "RUNTIME_VENV_ENV",
+    "BootstrapResult",
+    "ensure_local_runtime",
+]

cluxion_runtime/cli.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+"""cluxion-runtime 공통 CLI."""
+
+import argparse
+import json
+import sys
+from typing import TYPE_CHECKING
+
+from cluxion_runtime.adapters.contract import work_item_from_adapter_payload
+from cluxion_runtime.adapters.hermes import (
+    build_hermes_local_endpoint_patch,
+    hermes_config_patch_to_dict,
+    hermes_config_set_commands,
+    render_hermes_yaml_fragment,
+)
+from cluxion_runtime.bootstrap import ensure_local_runtime
+from cluxion_runtime.core.dispatch_store import (
+    DispatchStoreError,
+    build_briefing_payload,
+    next_dispatch_step,
+    persist_dispatch_bundle,
+    record_dispatch_result,
+)
+from cluxion_runtime.core.harness import build_harness_plan
+from cluxion_runtime.core.plan_codec import plan_to_dict
+from cluxion_runtime.core.types import AgentSurface, ModelRuntimeProfile
+from cluxion_runtime.models import LocalModelSupervisor, build_vllm_mlx_profile
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI 진입점."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "bootstrap":
+        return _run_bootstrap(args)
+    if args.command == "plan":
+        return _run_plan(args)
+    if args.command == "serve-local":
+        return _run_serve_local(args)
+    if args.command == "hermes-local-config":
+        return _run_hermes_local_config(args)
+    if args.command == "queue-next":
+        return _run_queue_next(args)
+    if args.command == "queue-record":
+        return _run_queue_record(args)
+    if args.command == "queue-brief":
+        return _run_queue_brief(args)
+    parser.print_help(sys.stderr)
+    return 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cluxion-runtime")
+    subparsers = parser.add_subparsers(dest="command")
+    bootstrap = subparsers.add_parser("bootstrap", help="로컬 모델 런타임 의존성을 자동 설치 또는 업그레이드")
+    bootstrap.add_argument("--upgrade", action="store_true", help="이미 설치되어도 최신 버전으로 업그레이드")
+    bootstrap.add_argument("--dry-run", action="store_true", help="설치하지 않고 실행할 installer 명령만 출력")
+    bootstrap.add_argument("--package", action="append", default=None, help="설치할 패키지 spec. 기본값: vllm-mlx")
+    plan = subparsers.add_parser("plan", help="외부 agent 작업을 Cluxion 하네스 계획으로 변환")
+    plan.add_argument("--surface", default=AgentSurface.API.value)
+    plan.add_argument("--work-id", default="")
+    plan.add_argument("--prompt", default="")
+    plan.add_argument("--model-route", default="host/default")
+    plan.add_argument("--priority", default="normal")
+    plan.add_argument("--expected-ram-mb", type=int, default=0)
+    plan.add_argument("--context-tokens", type=int, default=0)
+    plan.add_argument("--cwd", default="")
+    plan.add_argument("--json-stdin", action="store_true")
+    serve = subparsers.add_parser("serve-local", help="로컬 모델용 vLLM-MLX 서버 endpoint를 준비")
+    serve.add_argument("--model", required=True)
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8000)
+    serve.add_argument("--max-tokens", type=int, default=128_000)
+    serve.add_argument("--dry-run", action="store_true")
+    serve.add_argument("--auto-install", action=argparse.BooleanOptionalAction, default=True)
+    serve.add_argument("--upgrade-runtime", action="store_true")
+    hermes = subparsers.add_parser("hermes-local-config", help="Hermes custom provider용 로컬 endpoint 패치 출력")
+    hermes.add_argument("--model", required=True)
+    hermes.add_argument("--host", default="127.0.0.1")
+    hermes.add_argument("--port", type=int, default=8000)
+    hermes.add_argument("--max-tokens", type=int, default=128_000)
+    hermes.add_argument("--context-length", type=int, default=128_000)
+    hermes.add_argument("--provider-key", default="cluxion-local")
+    hermes.add_argument("--display-name", default="Cluxion Local")
+    queue_next = subparsers.add_parser("queue-next", help="저장된 dispatch queue에서 다음 segment를 반환")
+    queue_next.add_argument("--work-id", required=True)
+    queue_record = subparsers.add_parser("queue-record", help="segment 실행 결과를 dispatch queue에 기록")
+    queue_record.add_argument("--work-id", required=True)
+    queue_record.add_argument("--step-id", required=True)
+    queue_record.add_argument("--result", default="")
+    queue_record.add_argument("--error", default="")
+    queue_record.add_argument("--failed", action="store_true")
+    queue_record.add_argument("--json-stdin", action="store_true")
+    queue_brief = subparsers.add_parser("queue-brief", help="저장된 segment 결과를 최종 briefing prompt로 변환")
+    queue_brief.add_argument("--work-id", required=True)
+    return parser
+
+
+def _run_bootstrap(args: argparse.Namespace) -> int:
+    result = ensure_local_runtime(
+        packages=tuple(args.package) if args.package else ("vllm-mlx",),
+        upgrade=bool(args.upgrade),
+        dry_run=bool(args.dry_run),
+    )
+    print(json.dumps(result.to_dict(), ensure_ascii=False, sort_keys=True))
+    return 0 if result.ok else 1
+
+
+def _run_plan(args: argparse.Namespace) -> int:
+    surface = AgentSurface(str(args.surface))
+    payload = _payload_from_stdin() if args.json_stdin else _payload_from_args(args)
+    item = work_item_from_adapter_payload(payload, default_surface=surface)
+    plan = build_harness_plan(item)
+    persisted = persist_dispatch_bundle(plan)
+    output = plan_to_dict(plan)
+    if persisted is not None:
+        item_output = output.get("item")
+        if isinstance(item_output, dict):
+            item_output["original_prompt_stored"] = True
+        output["dispatch_store"] = {"stored": True, "path": str(persisted)}
+    print(json.dumps(output, ensure_ascii=False, sort_keys=True))
+    return 0
+
+
+def _run_queue_next(args: argparse.Namespace) -> int:
+    try:
+        payload = next_dispatch_step(str(args.work_id))
+    except DispatchStoreError as exc:
+        payload = {"ok": False, "error": str(exc)}
+        print(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+        return 1
+    print(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+    return 0
+
+
+def _run_queue_record(args: argparse.Namespace) -> int:
+    payload = _payload_from_stdin() if args.json_stdin else {}
+    result = str(payload.get("result", args.result))
+    error = str(payload.get("error", args.error))
+    failed = bool(payload.get("failed", args.failed))
+    try:
+        recorded = record_dispatch_result(
+            str(args.work_id),
+            str(args.step_id),
+            result=result,
+            error=error,
+            succeeded=not failed,
+        )
+    except DispatchStoreError as exc:
+        recorded = {"ok": False, "error": str(exc)}
+        print(json.dumps(recorded, ensure_ascii=False, sort_keys=True))
+        return 1
+    print(json.dumps(recorded, ensure_ascii=False, sort_keys=True))
+    return 0
+
+
+def _run_queue_brief(args: argparse.Namespace) -> int:
+    try:
+        payload = build_briefing_payload(str(args.work_id))
+    except DispatchStoreError as exc:
+        payload = {"ok": False, "error": str(exc)}
+        print(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+        return 1
+    print(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+    return 0
+
+
+def _run_serve_local(args: argparse.Namespace) -> int:
+    bootstrap = None
+    if args.auto_install and (not args.dry_run or args.upgrade_runtime):
+        bootstrap = ensure_local_runtime(upgrade=bool(args.upgrade_runtime))
+        if not bootstrap.ok:
+            profile = build_vllm_mlx_profile(
+                str(args.model),
+                host=str(args.host),
+                port=int(args.port),
+                max_tokens=int(args.max_tokens),
+            )
+            payload = _serve_payload(profile)
+            payload["bootstrap"] = bootstrap.to_dict()
+            payload.update({"started": False, "pid": 0, "reason": "bootstrap_failed"})
+            print(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+            return 1
+    elif args.auto_install and args.dry_run:
+        bootstrap = ensure_local_runtime(upgrade=bool(args.upgrade_runtime), dry_run=True)
+    executable = _runtime_executable(bootstrap) or "vllm-mlx"
+    profile = build_vllm_mlx_profile(
+        str(args.model),
+        host=str(args.host),
+        port=int(args.port),
+        max_tokens=int(args.max_tokens),
+        executable=executable,
+    )
+    payload = _serve_payload(profile)
+    if bootstrap is not None:
+        payload["bootstrap"] = bootstrap.to_dict()
+    if not args.dry_run:
+        result = LocalModelSupervisor(profile).start()
+        payload.update({"started": result.started, "pid": result.pid, "reason": result.reason})
+    print(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+    return 0
+
+
+def _runtime_executable(bootstrap: object) -> str | None:
+    if bootstrap is None:
+        return None
+    command_paths = getattr(bootstrap, "command_paths", None) or {}
+    value = command_paths.get("vllm-mlx")
+    return str(value) if value else None
+
+
+def _serve_payload(profile: ModelRuntimeProfile) -> dict[str, object]:
+    return {
+        "provider": "openai-compatible",
+        "runtime": profile.kind.value,
+        "model": profile.model,
+        "base_url": profile.base_url,
+        "command": list(profile.command),
+        "health_path": profile.health_path,
+        "started": False,
+        "pid": 0,
+    }
+
+
+def _run_hermes_local_config(args: argparse.Namespace) -> int:
+    profile = build_vllm_mlx_profile(
+        str(args.model),
+        host=str(args.host),
+        port=int(args.port),
+        max_tokens=int(args.max_tokens),
+    )
+    patch = build_hermes_local_endpoint_patch(
+        profile.model,
+        profile.base_url,
+        provider_key=str(args.provider_key),
+        display_name=str(args.display_name),
+        context_length=int(args.context_length),
+    )
+    payload = {
+        "provider": patch.provider_id,
+        "model": patch.model,
+        "base_url": patch.base_url,
+        "slash_model": patch.slash_model,
+        "serve_command": list(profile.command),
+        "config_patch": hermes_config_patch_to_dict(patch),
+        "config_set_commands": list(hermes_config_set_commands(patch)),
+        "yaml_fragment": render_hermes_yaml_fragment(patch),
+    }
+    print(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+    return 0
+
+
+def _payload_from_stdin() -> dict[str, object]:
+    raw = sys.stdin.read()
+    payload = json.loads(raw)
+    if not isinstance(payload, dict):
+        raise ValueError("stdin JSON은 object여야 한다.")
+    return dict(payload)
+
+
+def _payload_from_args(args: argparse.Namespace) -> dict[str, object]:
+    return {
+        "surface": str(args.surface),
+        "work_id": str(args.work_id),
+        "prompt": str(args.prompt),
+        "model_route": str(args.model_route),
+        "priority": str(args.priority),
+        "expected_ram_mb": int(args.expected_ram_mb),
+        "context_tokens": int(args.context_tokens),
+        "cwd": str(args.cwd),
+    }
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+__all__ = ["main"]

cluxion_runtime/core/__init__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+"""하네스 코어 공개 API."""
+
+from cluxion_runtime.core.harness import build_harness_plan
+from cluxion_runtime.core.intent import classify_intent
+from cluxion_runtime.core.ledger import DurableWorkLedger, LedgerEntry, RetryDecision, WorkStatus
+from cluxion_runtime.core.preprocess import preprocess_work
+from cluxion_runtime.core.types import (
+    AgentSurface,
+    AnswerPolicy,
+    HarnessPlan,
+    RuntimeKind,
+    WorkIntent,
+    WorkItem,
+    WorkPriority,
+)
+from cluxion_runtime.core.work_queue import AgentWorkQueue
+
+__all__ = [
+    "AgentSurface",
+    "AgentWorkQueue",
+    "AnswerPolicy",
+    "DurableWorkLedger",
+    "HarnessPlan",
+    "LedgerEntry",
+    "RetryDecision",
+    "RuntimeKind",
+    "WorkIntent",
+    "WorkItem",
+    "WorkPriority",
+    "WorkStatus",
+    "build_harness_plan",
+    "classify_intent",
+    "preprocess_work",
+]