zeroquantz 0.1.0__py3-none-any.whl

zeroquantz/__init__.py

@@ -0,0 +1,14 @@
+"""ZeroQuantz — interactive model optimization and quantization for the terminal.
+
+The top-level package deliberately imports *nothing* heavy at import time. The
+planning/recommendation core, CLI, and TUI depend only on lightweight libraries;
+torch/transformers/bitsandbytes/torchao are imported lazily by the components
+that actually need them. This keeps ``import zeroquantz`` fast and side-effect
+free, and lets the offline planning engine run on machines without a GPU.
+"""
+
+from __future__ import annotations
+
+from zeroquantz.version import __version__
+
+__all__ = ["__version__"]

zeroquantz/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m zeroquantz``."""
+
+from __future__ import annotations
+
+from zeroquantz.cli.app import main
+
+if __name__ == "__main__":
+    main()

zeroquantz/agent/__init__.py

@@ -0,0 +1,16 @@
+"""Intent parsing and dispatch: the funnel from user text to deterministic APIs."""
+
+from __future__ import annotations
+
+from zeroquantz.agent.dispatcher import CommandResult, Dispatcher
+from zeroquantz.agent.intents import Intent, IntentKind
+from zeroquantz.agent.parser import IntentParser, parse_goal
+
+__all__ = [
+    "CommandResult",
+    "Dispatcher",
+    "Intent",
+    "IntentKind",
+    "IntentParser",
+    "parse_goal",
+]

zeroquantz/agent/dispatcher.py

@@ -0,0 +1,520 @@
+"""Dispatch intents to deterministic application services.
+
+A single :class:`Dispatcher` maps each :class:`IntentKind` to a handler via a
+registry (no ``if kind == ...`` ladder). Both the CLI REPL and the TUI feed
+parsed intents through here, so natural language and slash commands always hit
+identical code paths. Handlers return a UI-agnostic :class:`CommandResult`; the
+rendering layer decides how to display it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from zeroquantz.agent.intents import Intent, IntentKind
+from zeroquantz.core.events import ProgressCallback, null_progress
+from zeroquantz.core.exceptions import CommandError, ZeroQuantzError
+from zeroquantz.utils.logging import get_logger
+
+# The optimization/profiling/inspection services (CandidateGenerator, Recommender,
+# MixedPrecisionPlanner, SensitivityProfiler, ModelInspector, pareto_frontier,
+# Objective) are imported lazily inside the handlers that use them. Importing the
+# Dispatcher is on the hot path of every `zeroquantz` invocation — including
+# `--version`/`--help` and shell completion — so keeping those (pydantic + the
+# whole optimization graph) out of module import time is a large cold-start win.
+
+if TYPE_CHECKING:
+    from zeroquantz.core.context import AppContext
+    from zeroquantz.models.metadata import ModelProfile
+
+log = get_logger(__name__)
+
+
+@dataclass
+class CommandResult:
+    """UI-agnostic outcome of dispatching one intent."""
+
+    kind: str
+    message: str = ""
+    payload: Any = None
+    success: bool = True
+    should_exit: bool = False
+
+
+# (command, description) pairs for /help and autocomplete.
+COMMANDS: tuple[tuple[str, str], ...] = (
+    ("/model <id>", "Load & inspect a model (Hub id or local path)"),
+    ("/inspect", "Show the current model's architecture and size"),
+    ("/hardware", "Show detected GPU, VRAM, and precision support"),
+    ("/goal <text>", "Set constraints, e.g. 'fit under 8GB target vllm quality'"),
+    ("/recommend", "Rank quantization strategies for the current goal"),
+    ("/profile", "Estimate per-layer sensitivity (heuristic)"),
+    ("/plan", "Build a mixed-precision plan for the budget"),
+    ("/quantize [method]", "Quantize the model (needs a backend + GPU)"),
+    ("/benchmark [path]", "Measure VRAM, latency, throughput"),
+    ("/compare", "Compare candidates and show the Pareto frontier"),
+    ("/verify <base> <quant>", "Compare quantized vs baseline quality"),
+    ("/export <dir>", "Write the ZeroQuantz report (and model if quantized)"),
+    ("/history", "Show the configuration history"),
+    ("/undo", "Revert the last configuration change"),
+    ("/checkout <n>", "Restore a history entry"),
+    ("/sessions", "List saved sessions"),
+    ("/save [name]", "Save the current session"),
+    ("/help", "Show this help"),
+    ("/exit", "Leave ZeroQuantz"),
+)
+
+Handler = Callable[["AppContext", Intent, ProgressCallback], CommandResult]
+
+
+class Dispatcher:
+    def __init__(self) -> None:
+        self._handlers: dict[IntentKind, Handler] = {
+            IntentKind.LOAD_MODEL: self._load_model,
+            IntentKind.INSPECT: self._inspect,
+            IntentKind.HARDWARE: self._hardware,
+            IntentKind.SET_GOAL: self._set_goal,
+            IntentKind.RECOMMEND: self._recommend,
+            IntentKind.PROFILE: self._profile,
+            IntentKind.PLAN: self._plan,
+            IntentKind.QUANTIZE: self._quantize,
+            IntentKind.BENCHMARK: self._benchmark,
+            IntentKind.COMPARE: self._compare,
+            IntentKind.VERIFY: self._verify,
+            IntentKind.EXPORT: self._export,
+            IntentKind.HISTORY: self._history,
+            IntentKind.UNDO: self._undo,
+            IntentKind.CHECKOUT: self._checkout,
+            IntentKind.SESSIONS: self._sessions,
+            IntentKind.SAVE: self._save,
+            IntentKind.LOAD_SESSION: self._load_session,
+            IntentKind.HELP: self._help,
+            IntentKind.EXIT: self._exit,
+            IntentKind.UNKNOWN: self._unknown,
+        }
+
+    def dispatch(
+        self,
+        intent: Intent,
+        ctx: AppContext,
+        progress: ProgressCallback = null_progress,
+    ) -> CommandResult:
+        handler = self._handlers.get(intent.kind, self._unknown)
+        try:
+            return handler(ctx, intent, progress)
+        except ZeroQuantzError as exc:
+            return CommandResult("error", exc.format(), payload=exc, success=False)
+        except Exception as exc:  # pragma: no cover - defensive
+            log.exception("unexpected error handling %s", intent.kind)
+            return CommandResult("error", f"Unexpected error: {exc}", success=False)
+
+    # ---- helpers ------------------------------------------------------------
+
+    @staticmethod
+    def _require_model(ctx: AppContext) -> ModelProfile:
+        if ctx.session.model_profile is None:
+            raise CommandError(
+                "No model loaded yet.",
+                suggestions=["/model Qwen/Qwen3-8B"],
+            )
+        return ctx.session.model_profile
+
+    @staticmethod
+    def _apply_goal_updates(ctx: AppContext, intent: Intent) -> list[str]:
+        updates = dict(intent.args.get("goal_updates") or {})
+        if not updates:
+            return []
+        if "objective" in updates:
+            from zeroquantz.optimization.constraints import Objective
+
+            updates["objective"] = Objective(updates["objective"])
+        ctx.session.goal = ctx.session.goal.with_updates(**updates)
+        ctx.candidates = []  # invalidate cached candidates
+        label = "set " + ", ".join(f"{k}={_fmt(v)}" for k, v in updates.items())
+        ctx.session.record(label)
+        return [label]
+
+    def _ensure_candidates(self, ctx: AppContext) -> list:
+        from zeroquantz.optimization.candidate import CandidateGenerator
+
+        model = self._require_model(ctx)
+        if not ctx.candidates:
+            ctx.candidates = CandidateGenerator.generate(
+                model, ctx.hardware, ctx.goal, registry=ctx.backends
+            )
+        return ctx.candidates
+
+    # ---- handlers -----------------------------------------------------------
+
+    def _load_model(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        from zeroquantz.models.inspector import ModelInspector
+
+        model_id = (intent.args.get("model_id") or "").strip()
+        if not model_id:
+            raise CommandError("Usage: /model <hf-id-or-path>", suggestions=["/model Qwen/Qwen3-8B"])
+        progress(f"Inspecting {model_id}", 0.2)
+        profile = ModelInspector.inspect(model_id)
+        progress("Loaded metadata", 1.0)
+        ctx.session.model_id = model_id
+        ctx.session.model_profile = profile
+        ctx.candidates = []
+        ctx.sensitivity = None
+        ctx.session.record(f"load {model_id}")
+        ctx.save()
+        return CommandResult("model", f"Model loaded: {model_id}", profile)
+
+    def _inspect(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        target = intent.args.get("target")
+        if target and target != ctx.session.model_id:
+            return self._load_model(ctx, Intent(IntentKind.LOAD_MODEL, {"model_id": target}), progress)
+        model = self._require_model(ctx)
+        return CommandResult("model", f"Model: {model.model_id}", model)
+
+    def _hardware(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        return CommandResult("hardware", f"Hardware: {ctx.hardware.gpu_name}", ctx.hardware)
+
+    def _set_goal(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        labels = self._apply_goal_updates(ctx, intent)
+        if not labels:
+            return CommandResult(
+                "message",
+                "No goal changes detected. Try: 'fit under 8GB', 'target vllm', 'optimize for quality'.",
+                ctx.goal,
+            )
+        ctx.save()
+        return CommandResult("goal", "Optimization goal updated.", ctx.goal)
+
+    def _recommend(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        from zeroquantz.optimization.recommender import Recommender
+
+        self._apply_goal_updates(ctx, intent)
+        cands = self._ensure_candidates(ctx)
+        ranked = Recommender.rank(cands, ctx.goal)
+        best = Recommender.recommend(cands, ctx.goal)
+        if best is not None:
+            ctx.session.selected_method = best.candidate.method
+        ctx.save()
+        return CommandResult(
+            "candidates",
+            "Ranked quantization strategies.",
+            {"ranked": ranked, "best": best, "goal": ctx.goal},
+        )
+
+    def _profile(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        from zeroquantz.profiling.sensitivity import SensitivityProfiler
+
+        model = self._require_model(ctx)
+        progress("Estimating layer sensitivity", 0.5)
+        profile = SensitivityProfiler.heuristic(model)
+        ctx.sensitivity = profile
+        progress("Done", 1.0)
+        return CommandResult(
+            "profile",
+            "Estimated per-layer sensitivity (heuristic prior). "
+            "Use `zeroquantz profile <model> --measured` for a measured pass.",
+            profile,
+        )
+
+    def _plan(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        from zeroquantz.optimization.planner import MixedPrecisionPlanner
+
+        self._apply_goal_updates(ctx, intent)
+        model = self._require_model(ctx)
+        progress("Planning precision assignment", 0.5)
+        plan = MixedPrecisionPlanner.plan(model, ctx.hardware, ctx.goal, ctx.sensitivity)
+        ctx.session.plan = plan
+        ctx.session.record("plan")
+        ctx.save()
+        return CommandResult("plan", "Mixed-precision plan ready.", plan)
+
+    def _quantize(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        from zeroquantz.quantization.catalog import Execution
+
+        model = self._require_model(ctx)
+        fmt = self._resolve_format(ctx, intent)
+        if fmt is None:
+            raise CommandError("No quantization strategy selected.", suggestions=["/recommend"])
+        ctx.session.selected_format_id = fmt.id
+        ctx.session.selected_method = fmt.method or fmt.id
+        # Prefer the locally-downloaded snapshot (from the download screen) if present.
+        model_ref = ctx.session.model_local_path or ctx.session.model_id or model.model_id
+        output = intent.args.get("output")
+
+        if fmt.execution is Execution.IN_ENV:
+            return self._quantize_in_env(ctx, fmt, model, model_ref, output, progress)
+        if fmt.execution is Execution.ISOLATED:
+            return self._quantize_isolated(ctx, fmt, model_ref, output, progress)
+        raise self._external_guidance(fmt, model_ref)
+
+    def _resolve_format(self, ctx: AppContext, intent: Intent):
+        from zeroquantz.optimization.recommender import Recommender
+        from zeroquantz.quantization import catalog
+
+        fid = intent.args.get("format_id") or ctx.session.selected_format_id
+        if fid and catalog.get_format(fid):
+            return catalog.get_format(fid)
+        method = intent.args.get("method") or ctx.session.selected_method
+        if method:
+            if catalog.get_format(method):
+                return catalog.get_format(method)
+            for f in catalog.ALL_FORMATS:
+                if f.method == method:
+                    return f
+        cands = self._ensure_candidates(ctx)
+        best = Recommender.recommend(cands, ctx.goal)
+        return catalog.get_format(best.candidate.format_id) if best else None
+
+    def _quantize_in_env(self, ctx, fmt, model, model_ref, output, progress):
+        backend = ctx.backends.get(fmt.backend)
+        err = backend.availability_error()
+        if err is not None:
+            raise err
+        if not ctx.hardware.cuda_available:
+            raise CommandError(
+                "Quantization needs a CUDA GPU, which was not detected.",
+                suggestions=["/recommend  (planning still works without a GPU)"],
+            )
+        config = backend.default_config(fmt.method, model, ctx.hardware, ctx.goal)
+        progress(f"Quantizing with {backend.name}:{fmt.method}", 0.1)
+        result = backend.quantize(model_ref, config, progress=progress)
+        ctx.last_quant_result = result
+        ctx.session.record(f"quantize {fmt.id}")
+        ctx.save()
+        if output:
+            from zeroquantz.export.exporter import Exporter
+
+            Exporter.export_model(result, output, backend)
+            result.output_dir = output
+            _record_quantized(output, ctx.session.model_id, fmt.id, fmt.method)
+        return CommandResult(
+            "quant", f"Quantized in-env with {fmt.label} in {result.elapsed_s:.1f}s.", result
+        )
+
+    def _quantize_isolated(self, ctx, fmt, model_ref, output, progress):
+        from pathlib import Path
+
+        from zeroquantz.quantization.base import QuantizationResult
+        from zeroquantz.quantization.config import QuantizationConfig
+        from zeroquantz.quantization.isolated import IsolatedEnvRunner
+
+        runner = IsolatedEnvRunner()
+        if not runner.supports(fmt.family):
+            raise self._external_guidance(fmt, model_ref)
+        name = model_ref.split("/")[-1]
+        out = output or str(Path.cwd() / f"zeroquantz-{name}-{fmt.id}")
+        progress(f"Building isolated {fmt.family} env (first run downloads the toolchain)", 0.02)
+        res = runner.quantize(
+            fmt, model_ref, out,
+            bits=max(2, round(fmt.bits_per_weight)),
+            cuda_version=ctx.hardware.cuda_version,
+            progress=progress,
+        )
+        config = QuantizationConfig(
+            backend=fmt.family, method=fmt.method or fmt.id,
+            weight_bits=max(1, min(16, round(fmt.bits_per_weight))),
+            activation_bits=fmt.activation_bits, extra={"format_id": fmt.id, "isolated": True},
+        )
+        result = QuantizationResult(
+            backend=fmt.family, method=fmt.id, config=config,
+            output_dir=res.output_dir, elapsed_s=res.elapsed_s,
+        )
+        ctx.last_quant_result = result
+        _record_quantized(res.output_dir, ctx.session.model_id, fmt.id, fmt.method or fmt.id)
+        ctx.session.record(f"quantize {fmt.id} (isolated)")
+        ctx.save()
+        return CommandResult(
+            "quant",
+            f"Quantized via isolated {fmt.family} env in {res.elapsed_s:.0f}s → {res.output_dir}",
+            result,
+        )
+
+    def _external_guidance(self, fmt, model_ref) -> CommandError:
+        if fmt.family == "bitnet":
+            return CommandError(
+                "BitNet b1.58 is a training-time (native-ternary) format, not a PTQ step.",
+                detail="Use a pre-trained BitNet checkpoint and run it with bitnet.cpp / llama.cpp.",
+            )
+        if "llamacpp" in fmt.runtimes:  # GGUF (incl. Unsloth dynamic GGUF)
+            qtype = fmt.id.replace("gguf_", "").replace("unsloth_ud_", "UD-").upper()
+            return CommandError(
+                f"'{fmt.label}' is produced with llama.cpp (not auto-run yet).",
+                detail="Convert to GGUF, then quantize:",
+                suggestions=[
+                    f"python convert_hf_to_gguf.py {model_ref} --outfile model.f16.gguf",
+                    f"llama-quantize model.f16.gguf {model_ref.split('/')[-1]}-{qtype}.gguf {qtype}",
+                ],
+            )
+        return CommandError(
+            f"'{fmt.label}' isn't auto-executed in this release.",
+            detail=f"Produced by {fmt.produced_by}. It is catalogued and estimated here; "
+            "execution is on the roadmap.",
+            suggestions=["/recommend  (pick an in-env or isolated format)", "/plan  (mixed precision)"],
+        )
+
+    def _benchmark(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        from zeroquantz.benchmark.runner import BenchmarkRunner
+
+        target = intent.args.get("target") or ctx.session.model_id
+        if not target:
+            raise CommandError("Usage: /benchmark <model-id-or-path>", suggestions=["/model <id>"])
+        result = BenchmarkRunner.run(
+            target,
+            warmup=ctx.config.benchmark.warmup_runs,
+            runs=ctx.config.benchmark.runs,
+            hardware=ctx.hardware,
+            progress=progress,
+        )
+        ctx.session.last_benchmark = result
+        ctx.session.record(f"benchmark {target}")
+        ctx.save()
+        return CommandResult("benchmark", f"Benchmarked {target}.", result)
+
+    def _compare(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        from zeroquantz.optimization.pareto import pareto_frontier
+        from zeroquantz.optimization.recommender import Recommender
+
+        cands = self._ensure_candidates(ctx)
+        ranked = Recommender.rank(cands, ctx.goal)[:20]
+        frontier = {id(c) for c in pareto_frontier(cands)}
+        return CommandResult(
+            "candidates",
+            "Candidate comparison (* = Pareto-optimal).",
+            {"ranked": ranked, "pareto_ids": frontier, "goal": ctx.goal, "compare": True},
+        )
+
+    def _verify(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        from zeroquantz.verification.report import Verifier
+
+        base = intent.args.get("base") or ctx.session.model_id
+        quant = intent.args.get("quant")
+        if not base or not quant:
+            raise CommandError(
+                "Usage: /verify <base-model> <quantized-path>",
+                suggestions=["/verify Qwen/Qwen3-8B ./qwen-nf4"],
+            )
+        report = Verifier.verify(base, quant, hardware=ctx.hardware, progress=progress)
+        ctx.session.last_verification = report
+        ctx.session.record(f"verify {quant}")
+        ctx.save()
+        return CommandResult("verification", f"Verification: {report.status}", report)
+
+    def _export(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        from zeroquantz.export.exporter import Exporter
+        from zeroquantz.export.report import build_report
+
+        path = intent.args.get("path")
+        if not path:
+            raise CommandError("Usage: /export <output-dir>", suggestions=["/export ./qwen-report"])
+        model = self._require_model(ctx)
+        config = None
+        if ctx.session.selected_method:
+            try:
+                backend = ctx.backends.get_for_method(ctx.session.selected_method)
+                config = backend.default_config(ctx.session.selected_method, model, ctx.hardware, ctx.goal)
+            except ZeroQuantzError:
+                config = None
+        report = build_report(
+            model,
+            config=config,
+            hardware=ctx.hardware,
+            goal=ctx.goal,
+            plan=ctx.session.plan,
+            benchmark=ctx.session.last_benchmark,
+            verification=ctx.session.last_verification,
+        )
+        if ctx.last_quant_result is not None and ctx.session.selected_method:
+            backend = ctx.backends.get_for_method(ctx.session.selected_method)
+            out = Exporter.export_model(ctx.last_quant_result, path, backend, report=report)
+            _record_quantized(str(out), ctx.session.model_id, ctx.session.selected_format_id, ctx.session.selected_method)
+            msg = f"Exported quantized model + report to {out}"
+        else:
+            json_path, md_path = Exporter.write_report(report, path)
+            msg = f"Wrote report:\n  {json_path}\n  {md_path}"
+        ctx.session.record(f"export {path}")
+        ctx.save()
+        return CommandResult("message", msg, report)
+
+    def _history(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        return CommandResult("history", "Configuration history.", ctx.session.history_view())
+
+    def _undo(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        label = ctx.session.undo()
+        if label is None:
+            return CommandResult("message", "Nothing to undo.")
+        # Model may have changed; drop a now-stale profile.
+        if ctx.session.model_profile and ctx.session.model_profile.model_id != ctx.session.model_id:
+            ctx.session.model_profile = None
+        ctx.candidates = []
+        ctx.save()
+        return CommandResult("message", f"Reverted '{label}'.", ctx.session)
+
+    def _checkout(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        index = intent.args.get("index")
+        if index is None:
+            raise CommandError("Usage: /checkout <history-index>", suggestions=["/history"])
+        snapshot = ctx.session.checkout(int(index))
+        ctx.candidates = []
+        ctx.save()
+        return CommandResult("message", f"Checked out #{index}: {snapshot.label}.", ctx.session)
+
+    def _sessions(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        return CommandResult("sessions", "Saved sessions.", ctx.repo.list())
+
+    def _save(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        name = intent.args.get("name")
+        if name:
+            ctx.session.name = name
+        elif ctx.session.name.startswith("scratch-"):
+            ctx.session.name = "default"
+        ctx.repo.save(ctx.session)
+        return CommandResult("message", f"Saved session '{ctx.session.name}'.")
+
+    def _load_session(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        name = (intent.args.get("name") or "").strip()
+        if not name:
+            raise CommandError("Usage: /load <session-name>", suggestions=["/sessions"])
+        session = ctx.repo.load(name)
+        session.hardware = ctx.hardware
+        ctx.session = session
+        ctx.candidates = []
+        return CommandResult("message", f"Loaded session '{name}'.", session)
+
+    def _help(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        return CommandResult("help", "ZeroQuantz commands.", COMMANDS)
+
+    def _exit(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        return CommandResult("exit", "Goodbye.", should_exit=True)
+
+    def _unknown(self, ctx: AppContext, intent: Intent, progress: ProgressCallback) -> CommandResult:
+        cmd = intent.args.get("command")
+        if cmd:
+            return CommandResult("error", f"Unknown command '/{cmd}'. Type /help.", success=False)
+        return CommandResult(
+            "message",
+            "I didn't catch a command there. Try /help, or say something like "
+            "'load Qwen/Qwen3-8B' or 'fit under 8GB for vllm'.",
+        )
+
+
+def _record_quantized(
+    path: str, base_model: str | None, format_id: str | None, method: str | None
+) -> None:
+    """Register a quantized output so Settings can list/manage it (best-effort)."""
+    try:
+        from zeroquantz.core.artifacts import default_quantized_registry
+
+        default_quantized_registry().add(
+            path, base_model=base_model, format_id=format_id, method=method
+        )
+    except Exception:  # pragma: no cover - never let bookkeeping break a quantize
+        log.debug("could not record quantized artifact at %s", path)
+
+
+def _fmt(value: Any) -> str:
+    from zeroquantz.optimization.constraints import Objective as _Obj
+
+    if isinstance(value, _Obj):
+        return value.value
+    return str(value)

zeroquantz/agent/intents.py

@@ -0,0 +1,46 @@
+"""Intent types.
+
+Natural language and slash commands both parse into a single :class:`Intent`
+(a ``kind`` plus a small ``args`` dict), which the dispatcher routes to a handler.
+Keeping one flat type — rather than a subclass per command — keeps the parser and
+the dispatch table simple and fully testable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class IntentKind(str, Enum):
+    LOAD_MODEL = "load_model"
+    INSPECT = "inspect"
+    HARDWARE = "hardware"
+    SET_GOAL = "set_goal"
+    RECOMMEND = "recommend"
+    PROFILE = "profile"
+    PLAN = "plan"
+    QUANTIZE = "quantize"
+    BENCHMARK = "benchmark"
+    COMPARE = "compare"
+    VERIFY = "verify"
+    EXPORT = "export"
+    HISTORY = "history"
+    UNDO = "undo"
+    CHECKOUT = "checkout"
+    SESSIONS = "sessions"
+    SAVE = "save"
+    LOAD_SESSION = "load_session"
+    HELP = "help"
+    EXIT = "exit"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class Intent:
+    kind: IntentKind
+    args: dict = field(default_factory=dict)
+    raw: str = ""
+
+    def __repr__(self) -> str:  # concise for tests
+        return f"Intent({self.kind.value}, {self.args})"