pcq 3.0.0__py3-none-any.whl

pcq/__init__.py

@@ -0,0 +1,133 @@
+"""pcq — ML authoring library on top of cq.yaml runtime contract.
+
+이 패키지는 cq.yaml 런타임 계약(CQ_CONFIG_JSON, stdout @key=value, output_dir)을
+감싸는 편의 계층이다.
+
+Note: cq.yaml / CQ_CONFIG_JSON / cq:// URI 스킴은 CQ Go service contract
+specification 으로, pcq 라이브러리 이름과 무관하게 그대로 유지된다.
+"""
+from pcq import _registry, agent, datasets, loss, metric, models, optim, sched, testing
+# v2.7: examples namespace — reference example implementations live under
+# pcq.examples.*. pcq.{models,datasets,optim,sched} remain compatibility facades.
+from pcq import examples
+from pcq.agent import (
+    ResolvedConfig,
+    RunContext,
+    compare_runs,
+    describe_run,
+    diff_recipes,
+    inspect_project,
+    list_meta,
+    recipe_meta,
+    resolve_project,
+    resolve_run_context,
+    summarize_run,
+    validate_project,
+)
+from pcq.contract import (
+    finalize_run,
+    save_all,
+    save_config_snapshot,
+    save_manifest,
+    save_metrics,
+    save_partial_run_record,
+    save_run_summary,
+)
+from pcq.core import config, input_dir, log, output_dir, seed_everything
+from pcq.experiment import Experiment
+from pcq.registry.spec import AtomRef, AtomSpec, ParamSpec
+from pcq.trainer import Trainer
+
+# 확장 API: Registry 함수/데코레이터 폼
+register_model = _registry.models.register
+register_dataset = _registry.datasets.register
+register_loss = _registry.losses.register
+register_optim = _registry.optims.register
+register_sched = _registry.scheds.register
+register_metric = _registry.metrics.register
+
+
+# Ref constructors (v1.8+) — agent 가 직렬화 가능한 atom 참조 생성
+def model_ref(name: str, params: dict | None = None) -> AtomRef:
+    """model AtomRef 생성. registry 의 model atom 을 직렬화 가능한 형태로 참조."""
+    return AtomRef(kind="model", name=name, params=dict(params or {}))
+
+
+def dataset_ref(name: str, params: dict | None = None) -> AtomRef:
+    """dataset AtomRef 생성."""
+    return AtomRef(kind="dataset", name=name, params=dict(params or {}))
+
+
+def loss_ref(name: str, params: dict | None = None) -> AtomRef:
+    """loss AtomRef 생성."""
+    return AtomRef(kind="loss", name=name, params=dict(params or {}))
+
+
+def optim_ref(name: str, params: dict | None = None) -> AtomRef:
+    """optimizer AtomRef 생성. params 에는 lr 등 hyperparam 만 (model.parameters() 제외)."""
+    return AtomRef(kind="optim", name=name, params=dict(params or {}))
+
+
+def sched_ref(name: str, params: dict | None = None) -> AtomRef:
+    """scheduler AtomRef 생성. params 에는 T_max 등만 (optimizer 제외)."""
+    return AtomRef(kind="sched", name=name, params=dict(params or {}))
+
+
+def metric_ref(name: str, params: dict | None = None) -> AtomRef:
+    """metric AtomRef 생성."""
+    return AtomRef(kind="metric", name=name, params=dict(params or {}))
+
+
+__version__ = "3.0.0"
+__all__ = [
+    "AtomRef",
+    "AtomSpec",
+    "Experiment",
+    "ParamSpec",
+    "ResolvedConfig",
+    "RunContext",
+    "Trainer",
+    "agent",
+    "compare_runs",
+    "config",
+    "dataset_ref",
+    "datasets",
+    "describe_run",
+    "diff_recipes",
+    "examples",
+    "finalize_run",
+    "input_dir",
+    "inspect_project",
+    "list_meta",
+    "log",
+    "loss",
+    "loss_ref",
+    "metric",
+    "metric_ref",
+    "model_ref",
+    "models",
+    "optim",
+    "optim_ref",
+    "output_dir",
+    "recipe_meta",
+    "register_dataset",
+    "register_loss",
+    "register_metric",
+    "register_model",
+    "register_optim",
+    "register_sched",
+    "resolve_project",
+    "resolve_run_context",
+    "save_all",
+    "save_config_snapshot",
+    "save_manifest",
+    "save_metrics",
+    "save_partial_run_record",
+    "save_run_summary",
+    "sched",
+    "sched_ref",
+    "seed_everything",
+    "summarize_run",
+    "testing",
+    "validate_project",
+]

pcq/_registry.py

@@ -0,0 +1,17 @@
+"""Backward compat shim — actual implementation moved to pcq.registry package.
+
+기존 `from pcq import _registry` 또는 `from pcq._registry import models` 패턴을
+유지하기 위한 thin re-export. 신규 코드는 `from pcq.registry import ...` 사용.
+"""
+from pcq.registry import (  # noqa: F401
+    AtomRef,
+    AtomSpec,
+    ParamSpec,
+    Registry,
+    datasets,
+    losses,
+    metrics,
+    models,
+    optims,
+    scheds,
+)

pcq/agent/__init__.py

@@ -0,0 +1,264 @@
+"""pcq.agent — agent metadata + inspection + validation + summary.
+
+v1.7 (Phase B): inspect / validate / summary 추가. 기존 v1.4 API
+(recipe_meta, diff_recipes, list_meta) 는 그대로 유지.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from torch import nn
+
+from pcq.agent.apply import (
+    ApplyResult,
+    PlanSetApplyResult,
+    apply_plan,
+    apply_planset,
+)
+from pcq.agent.compare import RunDiff, compare_runs
+from pcq.agent.describe import RunDescription, describe_run
+from pcq.agent.failure_classifier import classify_failure, enrich_failure
+from pcq.agent.init import InitResult, init_experiment
+from pcq.agent.install import (
+    AgentAssetStatus,
+    AgentInstallOperation,
+    AgentInstallResult,
+    AgentStatusResult,
+    agent_assets_status,
+    install_agent_assets,
+)
+from pcq.agent.json_contracts import (
+    JSON_CONTRACT_VERSION,
+    JSON_CONTRACTS,
+    get_json_contracts,
+    validate_json_contract,
+)
+from pcq.agent.inspect import inspect_project
+from pcq.agent.lineage import (
+    LineageChain,
+    LineageNode,
+    is_descendant_of,
+    lineage,
+)
+from pcq.agent.plan import (
+    ChangeOp,
+    ExperimentPlan,
+    ExperimentPlanSet,
+    ValidationPolicy,
+)
+from pcq.agent.resolver import (
+    ResolvedConfig,
+    RunContext,
+    resolve_project,
+    resolve_run_context,
+)
+from pcq.agent.run_record import (
+    ERROR_CODES,
+    AgentInfo,
+    EnvironmentInfo,
+    ExecutionInfo,
+    FailureInfo,
+    MetricsInfo,
+    RunInfo,
+    RunRecord,
+    SourceInfo,
+    ValidationInfo,
+    category_to_error_code,
+)
+from pcq.agent.scaffold import ScaffoldResult, scaffold_atom, validate_local_atoms
+from pcq.agent.schema import (
+    SCHEMA_VERSION,
+    CqYamlSummary,
+    EntrypointInfo,
+    EpochSummary,
+    OutputsInfo,
+    ProjectInspection,
+    RecipeInfo,
+    RecipeSpec,
+    RunSummary,
+    ValidationCheck,
+    ValidationReport,
+)
+from pcq.agent.smoke import SmokeReport, smoke_atom
+from pcq.agent.strictness import (
+    STRICTNESS_EVIDENCE_MATRIX,
+    strictness_evidence_matrix,
+    strictness_required_evidence,
+)
+from pcq.agent.summary import build_run_summary, summarize_run
+from pcq.agent.validate import validate_project
+from pcq.agent.validate_run import validate_run
+
+
+# recipe dict 의 metadata-only 키 (atom 이 아님)
+_META_KEYS = {
+    "task",
+    "metrics",
+    "requires_extras",
+    "smoke_safe",
+    "smoke_overrides",
+    "epochs",
+    "batch_size",
+}
+
+
+def _atom_summary(value: Any) -> str:
+    """atom (model/dataset/loss/lambda) 을 사람·agent 가 읽을 수 있게 요약.
+
+    nn.Module → "ClassName (instance)"
+    callable  → "callable<name>"
+    그 외     → 타입 이름
+    """
+    if isinstance(value, nn.Module):
+        return f"{type(value).__name__} (instance)"
+    if callable(value):
+        name = getattr(value, "__name__", "<lambda>")
+        return f"callable<{name}>"
+    return type(value).__name__
+
+
+def recipe_meta(preset: str) -> dict:
+    """Recipe metadata 추출. 학습 안 함, side effect 없음.
+
+    v1.4 API 유지. recipe 호출 실패(예: torchvision 미설치) 시 import_error
+    필드만 채워진 degraded dict 반환.
+    """
+    from pcq.trainer import _import_recipe
+
+    fn = _import_recipe(preset)
+    try:
+        d = fn()
+    except Exception as e:
+        return {
+            "name": preset,
+            "task": None,
+            "declared_metrics": [],
+            "requires_extras": [],
+            "smoke_safe": None,
+            "has_smoke_overrides": False,
+            "atoms": {},
+            "epochs": None,
+            "batch_size": None,
+            "import_error": f"{type(e).__name__}: {e}",
+        }
+
+    atom_keys = (
+        "model",
+        "dataset_train",
+        "dataset_eval",
+        "dataset",
+        "loss",
+        "optim_factory",
+        "sched_factory",
+    )
+    atoms: dict[str, str] = {}
+    for key in atom_keys:
+        if key in d:
+            atoms[key] = _atom_summary(d[key])
+
+    return {
+        "name": preset,
+        "task": d.get("task", "classification"),
+        "declared_metrics": list(d.get("metrics", [])),
+        "requires_extras": list(d.get("requires_extras", [])),
+        "smoke_safe": d.get("smoke_safe"),
+        "has_smoke_overrides": bool(d.get("smoke_overrides")),
+        "atoms": atoms,
+        "epochs": d.get("epochs"),
+        "batch_size": d.get("batch_size"),
+    }
+
+
+def diff_recipes(a: str, b: str) -> dict:
+    """두 recipe 의 atom + 설정 diff. agent 가 두 baseline 비교 시."""
+    ma, mb = recipe_meta(a), recipe_meta(b)
+    diff: dict[str, dict] = {}
+    for key in set(ma.keys()) | set(mb.keys()):
+        va, vb = ma.get(key), mb.get(key)
+        if va != vb:
+            diff[key] = {"a": va, "b": vb}
+    return {"a": a, "b": b, "diff": diff}
+
+
+def list_meta() -> list[dict]:
+    """모든 등록된 recipe 의 metadata. agent 가 catalog 를 둘러볼 때."""
+    from pcq.trainer import Trainer
+
+    return [recipe_meta(p) for p in Trainer.list_presets()]
+
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "AgentInfo",
+    "AgentAssetStatus",
+    "AgentInstallOperation",
+    "AgentInstallResult",
+    "AgentStatusResult",
+    "ApplyResult",
+    "ChangeOp",
+    "CqYamlSummary",
+    "EntrypointInfo",
+    "EnvironmentInfo",
+    "EpochSummary",
+    "ERROR_CODES",
+    "ExecutionInfo",
+    "ExperimentPlan",
+    "ExperimentPlanSet",
+    "FailureInfo",
+    "InitResult",
+    "JSON_CONTRACT_VERSION",
+    "JSON_CONTRACTS",
+    "LineageChain",
+    "LineageNode",
+    "MetricsInfo",
+    "OutputsInfo",
+    "PlanSetApplyResult",
+    "ProjectInspection",
+    "RecipeInfo",
+    "RecipeSpec",
+    "ResolvedConfig",
+    "RunContext",
+    "RunDescription",
+    "RunDiff",
+    "RunInfo",
+    "RunRecord",
+    "RunSummary",
+    "ScaffoldResult",
+    "SmokeReport",
+    "SourceInfo",
+    "STRICTNESS_EVIDENCE_MATRIX",
+    "ValidationCheck",
+    "ValidationInfo",
+    "ValidationPolicy",
+    "ValidationReport",
+    "_atom_summary",
+    "apply_plan",
+    "apply_planset",
+    "build_run_summary",
+    "category_to_error_code",
+    "classify_failure",
+    "compare_runs",
+    "describe_run",
+    "diff_recipes",
+    "enrich_failure",
+    "get_json_contracts",
+    "init_experiment",
+    "agent_assets_status",
+    "install_agent_assets",
+    "inspect_project",
+    "is_descendant_of",
+    "lineage",
+    "list_meta",
+    "recipe_meta",
+    "resolve_project",
+    "resolve_run_context",
+    "scaffold_atom",
+    "smoke_atom",
+    "strictness_evidence_matrix",
+    "strictness_required_evidence",
+    "summarize_run",
+    "validate_local_atoms",
+    "validate_json_contract",
+    "validate_project",
+    "validate_run",
+]