dagnam 0.7.0__py3-none-any.whl

dagnam/NOTICE

@@ -0,0 +1,8 @@
+dagnam
+Copyright 2026 Dagnam.AI
+
+This product includes software developed by Dagnam.AI.
+
+Dagnam.AI, Dagnam, and related names are trademarks or service marks of
+Dagnam.AI. The Apache License 2.0 does not grant trademark rights except as
+required for describing the origin of this work.

dagnam/__init__.py

@@ -0,0 +1,220 @@
+"""dagnam - Python client library for Dagnam.AI datasets."""
+
+from __future__ import annotations
+
+import logging as _logging
+
+# Attach a NullHandler before any subpackage import so a DEBUG log emitted while
+# dagnam.* wires itself up never falls through to logging.lastResort (the
+# idiomatic PyPI-library logging contract — the app configures logging, not us).
+# This one non-import statement must precede all imports below, so E402 is
+# ignored file-wide in pyproject.toml with a documented reason.
+_logging.getLogger("dagnam").addHandler(_logging.NullHandler())
+
+from typing import TYPE_CHECKING, Any
+
+from dagnam._core._logging import enable_debug_logging
+from dagnam._core.auth import configure, get_api_key, get_api_url
+from dagnam._core.client import DagnamClient
+from dagnam._core.config import get_config_value
+from dagnam._core.lro import LongRunningOperation
+from dagnam.data.cache import (
+    compute_file_checksum,
+    evict_lru,
+    get_cache_dir,
+    is_cached,
+    load_metadata,
+    save_checksum,
+    save_metadata,
+    touch_cache,
+)
+from dagnam.exceptions import (
+    APIError,
+    ArchitectureValidationError,
+    ArchitectureVersionNotFoundError,
+    AuthError,
+    CheckpointError,
+    CheckpointNotFoundError,
+    ChecksumError,
+    CodegenError,
+    CodegenValidationError,
+    DagnamError,
+    DatasetNotFoundError,
+    DeploymentNotFoundError,
+    DeploymentStateError,
+    DeploymentValidationError,
+    HubError,
+    HubModelNotFoundError,
+    LROFailedError,
+    LROTimeoutError,
+    ProjectNotFoundError,
+    QuotaExceededError,
+    ResponseError,
+    StreamError,
+    TaskNotFoundError,
+    TrainingJobNotFoundError,
+    UploadError,
+)
+from dagnam.resources import account, codegen, datasets, deployments, hub, projects, studio
+from dagnam.resources.checkpoints import download_checkpoint
+from dagnam.resources.datasets import (
+    delete_dataset,
+    preview_dataset,
+    update_dataset,
+    update_dataset_roles,
+)
+from dagnam.resources.inference import (
+    deployment_health,
+    inference,
+    inference_batch,
+    inference_schema,
+    inference_stream,
+)
+from dagnam.resources.projects import (
+    download_project_thumbnail,
+    upload_project_thumbnail,
+)
+from dagnam.resources.training import (
+    TrainingEvent,
+    allowed_strategies,
+    cancel_training_job,
+    create_training_job,
+    delete_training_jobs,
+    download_code,
+    download_dag,
+    estimate_resources,
+    get_training_job,
+    list_training_jobs,
+    restart,
+    restore_checkpoint,
+    stream_training,
+    training_logs,
+    training_metrics,
+    training_metrics_summary,
+)
+from dagnam.training import (
+    init,
+    report_error,
+    report_log,
+    report_metric,
+    report_progress,
+    report_system,
+    write_training_state,
+)
+
+__version__ = "0.7.0"
+
+if TYPE_CHECKING:
+    # Declared for type checkers and ``__all__``; loaded lazily at runtime via
+    # ``__getattr__`` (see ``_LAZY_EXPORTS``) to keep import time low.
+    from dagnam._core.aio import AsyncDagnamClient
+    from dagnam.data.dataset import DagnamDataset
+    from dagnam.data.load import load_dataset
+
+_LAZY_EXPORTS = {
+    "AsyncDagnamClient": ("dagnam._core.aio", "AsyncDagnamClient"),
+    "DagnamDataset": ("dagnam.data.dataset", "DagnamDataset"),
+    "load_dataset": ("dagnam.data.load", "load_dataset"),
+}
+
+__all__ = [
+    "APIError",
+    "ArchitectureValidationError",
+    "ArchitectureVersionNotFoundError",
+    "AsyncDagnamClient",
+    "AuthError",
+    "CheckpointError",
+    "CheckpointNotFoundError",
+    "ChecksumError",
+    "CodegenError",
+    "CodegenValidationError",
+    "DagnamClient",
+    "DagnamDataset",
+    "DagnamError",
+    "DatasetNotFoundError",
+    "DeploymentNotFoundError",
+    "DeploymentStateError",
+    "DeploymentValidationError",
+    "HubError",
+    "HubModelNotFoundError",
+    "LROFailedError",
+    "LROTimeoutError",
+    "LongRunningOperation",
+    "ProjectNotFoundError",
+    "QuotaExceededError",
+    "ResponseError",
+    "StreamError",
+    "TaskNotFoundError",
+    "TrainingEvent",
+    "TrainingJobNotFoundError",
+    "UploadError",
+    "__version__",
+    "account",
+    "allowed_strategies",
+    "cancel_training_job",
+    "codegen",
+    "compute_file_checksum",
+    "configure",
+    "create_training_job",
+    "datasets",
+    "delete_dataset",
+    "delete_training_jobs",
+    "deployment_health",
+    "deployments",
+    "download_checkpoint",
+    "download_code",
+    "download_dag",
+    "download_project_thumbnail",
+    "enable_debug_logging",
+    "estimate_resources",
+    "evict_lru",
+    "get_api_key",
+    "get_api_url",
+    "get_cache_dir",
+    "get_config_value",
+    "get_training_job",
+    "hub",
+    "inference",
+    "inference_batch",
+    "inference_schema",
+    "inference_stream",
+    "init",
+    "is_cached",
+    "list_training_jobs",
+    "load_dataset",
+    "load_metadata",
+    "preview_dataset",
+    "projects",
+    "report_error",
+    "report_log",
+    "report_metric",
+    "report_progress",
+    "report_system",
+    "restart",
+    "restore_checkpoint",
+    "save_checksum",
+    "save_metadata",
+    "stream_training",
+    "studio",
+    "touch_cache",
+    "training_logs",
+    "training_metrics",
+    "training_metrics_summary",
+    "update_dataset",
+    "update_dataset_roles",
+    "upload_project_thumbnail",
+    "write_training_state",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Load optional/heavy public exports only when callers request them."""
+    if name not in _LAZY_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from importlib import import_module
+
+    module_name, attr_name = _LAZY_EXPORTS[name]
+    value = getattr(import_module(module_name), attr_name)
+    globals()[name] = value
+    return value

dagnam/_agent/__init__.py

@@ -0,0 +1,11 @@
+"""Agent-integration assets and installer.
+
+This private package bundles the cross-platform Agent Skill (``skill/``) plus the
+Claude Code and Codex adapter files (``claude/``, ``codex/``), and the importable
+logic that powers them (``install.py``, ``runner.py``, ``guardhook.py``). It ships
+as package data so ``dagnam agent install`` can locate it via ``importlib.resources``
+after a pip install.
+
+It must never import ``dagnam.cli`` (the CLI depends on this package, not the
+reverse); the installed version is read via ``importlib.metadata`` instead.
+"""

dagnam/_agent/claude/agents/dagnam-runner.md

@@ -0,0 +1,16 @@
+---
+name: dagnam-runner
+description: Runs long Dagnam train->watch->eval->deploy loops in an isolated context. Use when a training job or deployment must be driven to completion so its SSE metric stream and long-running-operation polling stay off the main conversation.
+tools: Bash, Read
+---
+
+You drive long-running Dagnam operations to completion in isolation.
+
+- Stream training with `python <skill_dir>/scripts/watch_training.py <job_id>` (or
+  `dagnam stream <job_id> --json`) and report only the final outcome
+  (`complete` / `failed` / `cancelled`) plus a one-line metric summary — never paste the
+  full event stream back.
+- Poll long-running operations with the SDK: `op.wait(timeout=...).result()`.
+- Honor the GUARDRAIL: never start a costly action yourself (create a training job, create or
+  delete a deployment, delete a project/job, or publish to the hub). If the loop reaches such a
+  step, stop and return control with the proposed plan for the user to confirm.

dagnam/_agent/claude/hooks/guard.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python -m dagnam._agent.guardhook"
+          }
+        ]
+      }
+    ]
+  }
+}

dagnam/_agent/claude/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "dagnam",
+  "version": "0.0.0",
+  "description": "Drive the Dagnam platform (datasets, projects, codegen, training, deployments, inference, hub) from Claude Code. Pairs with the `dagnam` skill installed at ~/.claude/skills/dagnam.",
+  "author": "Dagnam.AI",
+  "agents": ["./agents/dagnam-runner.md"],
+  "hooks": "./hooks/guard.json"
+}

dagnam/_agent/codex/agents/openai.yaml

@@ -0,0 +1,4 @@
+name: dagnam
+version: 0.0.0
+description: Drive the Dagnam platform from Codex (datasets, projects, codegen, training, deployments, inference, hub).
+allow_implicit_invocation: true

dagnam/_agent/codex/hooks.json

@@ -0,0 +1,7 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      { "command": ["python", "-m", "dagnam._agent.guardhook"] }
+    ]
+  }
+}

dagnam/_agent/guardhook.py

@@ -0,0 +1,74 @@
+"""Cross-platform PreToolUse hook: deny un-confirmed costly Dagnam commands.
+
+Reads the harness hook event (JSON on stdin) and, if the Bash command runs a costly
+Dagnam action (deployments create/delete, training create/delete, projects delete,
+hub publish, or a public visibility flag) WITHOUT an explicit ``DAGNAM_CONFIRM=1``
+prefix, emits a deny decision. Both the CLI verb shape (``dagnam deployments create``)
+and the Python SDK shape (``python -c "import dagnam; dagnam.deployments.create(...)"``,
+which ``SKILL.md`` recommends) are matched.
+
+This hook is **non-authoritative, best-effort defense-in-depth ONLY.** It has known
+blind spots -- command obfuscation (base64/eval, string-built attribute names),
+aliasing, imports under a different module name, and any non-Bash tool the agent
+might use -- and it fails OPEN on any error so it can never wedge the agent. The
+authoritative gate is the ``SKILL.md`` behavioral rule plus server-side confirmation
+enforcement; this hook only hardens them. The ``visibility=public`` heuristic is
+deliberately broad and will occasionally deny a benign public create/upload -- an
+accepted false positive, since a denial only asks the operator to re-run with a
+``DAGNAM_CONFIRM=1`` prefix.
+
+Prints to stdout by design (the hook protocol), so it is T20-exempt.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+
+# Costly actions in BOTH the CLI verb shape and the Python SDK shape. re.DOTALL so a
+# newline between ``dagnam`` and the action (a multi-line or line-continuation
+# command) cannot hide it from the deny check.
+_COSTLY = re.compile(
+    r"\bdagnam\b.*\b(?:"
+    r"deployments?\s+(?:create|delete)"  # CLI: dagnam deployments create
+    r"|training\s+(?:create|delete)"
+    r"|projects?\s+delete"
+    r"|deployments?\s*\.\s*(?:create|delete)"  # SDK: dagnam.deployments.create(
+    r"|training\s*\.\s*(?:create|delete)"  # SDK: dagnam.training.create(
+    r"|projects?\s*\.\s*delete"
+    r"|hub\s*\.\s*create"  # SDK: publish to the hub
+    r"|create_training_job"
+    r"|visibility\s*=\s*[\\'\"]*public"  # any public create/upload (quotes/escapes optional)
+    r")",
+    re.DOTALL,
+)
+# Anchor the confirm token to a command-leading env assignment (start of line,
+# or the first token after a shell separator). Matching it ANYWHERE let a
+# hostile string echoed into an argument -- e.g. a dataset description
+# "... DAGNAM_CONFIRM=1" surfaced via prompt injection -- silently satisfy the
+# gate. It must be a real prefix the operator typed, not incidental text.
+_CONFIRMED = re.compile(r"(?:^|[;&|\n]\s*)DAGNAM_CONFIRM=1\b")
+_DENY_REASON = (
+    "Dagnam guardrail: this is a costly/irreversible action. Show the user an execution "
+    "plan (scripts/plan.py, or codegen.validate/preview + account.entitlements) and get "
+    "explicit confirmation, then re-run the command prefixed with DAGNAM_CONFIRM=1."
+)
+
+
+def main() -> int:
+    """Entry point wired by claude/hooks/guard.json and codex/hooks.json."""
+    try:
+        event = json.load(sys.stdin)
+        command = str(event.get("tool_input", {}).get("command", ""))
+    except (json.JSONDecodeError, AttributeError, ValueError):
+        return 0  # fail-open
+    if _COSTLY.search(command) and not _CONFIRMED.search(command):
+        json.dump(
+            {"permissionDecision": "deny", "permissionDecisionReason": _DENY_REASON}, sys.stdout
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dagnam/_agent/install.py

@@ -0,0 +1,274 @@
+"""Detect installed agent harnesses and wire the Dagnam skill into each.
+
+Pure logic: returns dataclasses describing planned/performed actions; it never prints
+or prompts (``dagnam.cli.agent`` owns presentation). It must not import ``dagnam.cli``;
+the installed version is read via ``importlib.metadata``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib import resources
+from importlib.metadata import PackageNotFoundError, version
+import json
+from pathlib import Path
+import shutil
+import sys
+
+Harness = str  # "claude" | "codex"
+
+# The guard hook must run under the SAME interpreter that has ``dagnam``
+# installed. A bare ``python`` on PATH may resolve to a different interpreter
+# (pipx / uv-tool / venv installs), where ``-m dagnam._agent.guardhook`` raises
+# ModuleNotFoundError and breaks every matched tool call. Pin ``sys.executable``.
+_GUARD_HOOK_MODULE_ARGS = ["-m", "dagnam._agent.guardhook"]
+
+
+def _guard_hook_entry() -> dict[str, object]:
+    """The Codex ``hooks.json`` guard entry, pinned to the current interpreter."""
+    return {"command": [sys.executable, *_GUARD_HOOK_MODULE_ARGS]}
+
+
+def _is_guard_hook_entry(entry: object) -> bool:
+    """True if ``entry`` is our guard hook.
+
+    Matches regardless of which interpreter path it was written with, so
+    re-install stays idempotent and uninstall can find it even if the
+    interpreter moved.
+    """
+    if not isinstance(entry, dict):
+        return False
+    command = entry.get("command")
+    return isinstance(command, list) and command[-2:] == _GUARD_HOOK_MODULE_ARGS
+
+
+@dataclass(frozen=True)
+class InstallPlan:
+    """What ``install_harness`` will write for one harness (no side effects)."""
+
+    harness: Harness
+    skill_dest: Path
+    extra_dests: tuple[Path, ...] = ()
+
+
+@dataclass
+class InstallResult:
+    """What ``install_harness`` actually wrote for one harness."""
+
+    harness: Harness
+    skill_dest: Path
+    method: str  # "symlink" | "copy"
+    wrote: list[Path] = field(default_factory=list)
+
+
+def _home() -> Path:
+    return Path.home()
+
+
+def _assets_root() -> Path:
+    """Filesystem path to the bundled ``dagnam/_agent`` assets (works post-pip-install)."""
+    return Path(str(resources.files("dagnam._agent")))
+
+
+def package_version() -> str:
+    """Installed dagnam version, falling back to the in-tree value for source checkouts."""
+    try:
+        return version("dagnam")
+    except PackageNotFoundError:
+        from dagnam import __version__
+
+        return __version__
+
+
+def detect_harnesses() -> list[Harness]:
+    """Return installed harnesses in stable order. Claude -> ~/.claude; Codex -> ~/.codex or ~/.agents."""
+    home = _home()
+    found: list[Harness] = []
+    if (home / ".claude").exists():
+        found.append("claude")
+    if (home / ".codex").exists() or (home / ".agents").exists():
+        found.append("codex")
+    return found
+
+
+def _skill_dest(harness: Harness) -> Path:
+    home = _home()
+    if harness == "claude":
+        return home / ".claude" / "skills" / "dagnam"
+    return home / ".agents" / "skills" / "dagnam"  # codex
+
+
+def _claude_plugin_dir() -> Path:
+    return _home() / ".claude" / "plugins" / "dagnam"
+
+
+def plan_for(harness: Harness) -> InstallPlan:
+    """Describe the install destinations for a harness without writing anything."""
+    extra: tuple[Path, ...]
+    if harness == "claude":
+        extra = (_claude_plugin_dir(),)
+    else:
+        extra = (_home() / ".codex" / "hooks.json",)
+    return InstallPlan(harness=harness, skill_dest=_skill_dest(harness), extra_dests=extra)
+
+
+def _remove_dest(dest: Path) -> bool:
+    """Remove ``dest`` whether it is a symlink or a real directory. Returns True if removed."""
+    if dest.is_symlink():
+        dest.unlink()
+        return True
+    if dest.exists():
+        shutil.rmtree(dest)
+        return True
+    return False
+
+
+def _try_symlink(dest: Path, src: Path) -> bool:
+    """Attempt a directory symlink; return False on OSError (e.g. unprivileged Windows)."""
+    try:
+        dest.symlink_to(src, target_is_directory=True)
+    except OSError:
+        return False
+    return True
+
+
+def _copy_tree(src: Path, dest: Path) -> None:
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(src, dest)
+
+
+def _place_skill(method: str, dest: Path) -> str:
+    """Copy or symlink the bundled ``skill/`` into ``dest``. Returns the method used."""
+    src = _assets_root() / "skill"
+    _remove_dest(dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if method == "symlink" and _try_symlink(dest, src):
+        return "symlink"
+    _copy_tree(src, dest)
+    return "copy"
+
+
+def _stamp_version(path: Path, key: str = "version") -> None:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    data[key] = package_version()
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _merge_codex_hook(wrote: list[Path]) -> None:
+    """Idempotently merge the guard hook into ``~/.codex/hooks.json``, preserving other entries."""
+    codex = _home() / ".codex"
+    codex.mkdir(parents=True, exist_ok=True)
+    hooks_path = codex / "hooks.json"
+    data: dict[str, object] = {}
+    if hooks_path.exists():
+        try:
+            loaded = json.loads(hooks_path.read_text(encoding="utf-8"))
+            data = loaded if isinstance(loaded, dict) else {}
+        except json.JSONDecodeError:
+            data = {}
+    hooks = data.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        hooks = {}
+        data["hooks"] = hooks
+    pre = hooks.setdefault("PreToolUse", [])
+    if not isinstance(pre, list):
+        pre = []
+        hooks["PreToolUse"] = pre
+    if not any(_is_guard_hook_entry(entry) for entry in pre):
+        pre.append(_guard_hook_entry())
+    hooks_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    wrote.append(hooks_path)
+
+
+def _install_codex_extras(wrote: list[Path]) -> None:
+    """Place + version-stamp the Codex skill metadata, then merge the guard hook."""
+    dest_agents = _skill_dest("codex") / "agents"
+    dest_agents.mkdir(parents=True, exist_ok=True)
+    src_yaml = _assets_root() / "codex" / "agents" / "openai.yaml"
+    yaml_text = src_yaml.read_text(encoding="utf-8").replace(
+        "version: 0.0.0", f"version: {package_version()}"
+    )
+    yaml_path = dest_agents / "openai.yaml"
+    yaml_path.write_text(yaml_text, encoding="utf-8")
+    wrote.append(yaml_path)
+    _merge_codex_hook(wrote)
+
+
+def install_harness(harness: Harness, *, method: str = "copy") -> InstallResult:
+    """Install the skill (and adapter files) for one harness. Idempotent."""
+    dest = _skill_dest(harness)
+    used = _place_skill(method, dest)
+    wrote = [dest]
+    if harness == "claude":
+        plugin_dir = _claude_plugin_dir()
+        _copy_tree(_assets_root() / "claude", plugin_dir)
+        _stamp_version(plugin_dir / "plugin.json")
+        _stamp_claude_guard_interpreter(plugin_dir / "hooks" / "guard.json")
+        wrote.append(plugin_dir)
+    else:  # codex
+        _install_codex_extras(wrote)
+    return InstallResult(harness=harness, skill_dest=dest, method=used, wrote=wrote)
+
+
+def _stamp_claude_guard_interpreter(guard_path: Path) -> None:
+    """Rewrite the copied Claude guard hook to invoke the current interpreter.
+
+    The bundled asset ships a bare ``python`` command; pin it to
+    ``sys.executable`` (double-quoted so a path with spaces survives the shell)
+    for the same reason as the Codex entry — a different PATH ``python`` cannot
+    import ``dagnam``.
+    """
+    data = json.loads(guard_path.read_text(encoding="utf-8"))
+    command = f'"{sys.executable}" ' + " ".join(_GUARD_HOOK_MODULE_ARGS)
+    for group in data.get("hooks", {}).get("PreToolUse", []):
+        for hook in group.get("hooks", []):
+            if isinstance(hook, dict) and "-m dagnam._agent.guardhook" in str(hook.get("command")):
+                hook["command"] = command
+    guard_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _unmerge_codex_hook() -> list[Path]:
+    """Remove our guard entry from ``~/.codex/hooks.json``, leaving others intact.
+
+    Mirrors ``_merge_codex_hook`` so a codex uninstall — or a plain
+    ``pip uninstall dagnam`` follow-up — doesn't leave the hook firing against a
+    now-missing module.
+    """
+    hooks_path = _home() / ".codex" / "hooks.json"
+    if not hooks_path.exists():
+        return []
+    try:
+        data = json.loads(hooks_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return []
+    if not isinstance(data, dict):
+        return []
+    hooks = data.get("hooks")
+    if not isinstance(hooks, dict):
+        return []
+    pre = hooks.get("PreToolUse")
+    if not isinstance(pre, list):
+        return []
+    kept = [entry for entry in pre if not _is_guard_hook_entry(entry)]
+    if len(kept) == len(pre):
+        return []
+    hooks["PreToolUse"] = kept
+    hooks_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return [hooks_path]
+
+
+def uninstall_harness(harness: Harness) -> list[Path]:
+    """Remove what ``install_harness`` wrote for a harness. Returns removed paths. Idempotent."""
+    removed: list[Path] = []
+    dest = _skill_dest(harness)
+    if _remove_dest(dest):
+        removed.append(dest)
+    if harness == "claude":
+        plugin_dir = _claude_plugin_dir()
+        if plugin_dir.exists():
+            shutil.rmtree(plugin_dir)
+            removed.append(plugin_dir)
+    else:  # codex
+        removed.extend(_unmerge_codex_hook())
+    return removed