ecocodes 1.0.0__py3-none-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
ecocode/__init__.py ADDED
@@ -0,0 +1,161 @@
1
+ """
2
+ EcoCode Python SDK
3
+
4
+ Track energy consumption of ML training and inference runs: phases, epochs,
5
+ token counts, optimizer steps, loss, learning rate, and sequence length.
6
+
7
+ Three equivalent usage patterns:
8
+
9
+ Context manager:
10
+ with ecocode.run("experiment", exporter="terminal") as r:
11
+ r.mark("phase", "forward")
12
+ r.log_loss(1.45)
13
+
14
+ Decorator:
15
+ @ecocode.track("experiment", exporter="terminal")
16
+ def train(): ...
17
+
18
+ Explicit start/stop:
19
+ r = ecocode.run("experiment", exporter="terminal")
20
+ r.start()
21
+ train()
22
+ r.stop()
23
+
24
+ Exporter options:
25
+ exporter="terminal" (default) Print live metrics to stdout.
26
+ exporter="csv" Write to a CSV file (requires output_file=).
27
+ exporter="json" Write to a JSON file (requires output_file=).
28
+ exporter="online" Send to the EcoCode dashboard
29
+ (requires api_key= or ECOCODE_API_KEY).
30
+
31
+ Attached mode (CLI wrapping) is auto-detected from environment variables.
32
+
33
+ ML Phase labels (use these consistently for cross-run comparisons):
34
+ Pretraining / SFT : data_loading, tokenization, forward, backward,
35
+ optimizer_step, eval, checkpoint_save, done
36
+ RLHF : reward_model, policy_rollout, reference_forward,
37
+ ppo_update, dpo_update, grpo_update, kl_penalty
38
+ Inference : model_load, prefill, decode, kv_cache_ops, done
39
+
40
+ Additional methods:
41
+ run.log_custom(key, value) Log arbitrary numeric metrics (gradient norm,
42
+ perplexity, BLEU, reward score, batch size, etc.)
43
+
44
+ Framework integrations:
45
+ ecocode.integrations.huggingface HuggingFace Trainer
46
+ ecocode.integrations.trl TRL (SFT, DPO, GRPO)
47
+ ecocode.integrations.lightning PyTorch Lightning
48
+ ecocode.integrations.deepspeed DeepSpeed
49
+ ecocode.integrations.vllm vLLM (async inference)
50
+ ecocode.integrations.keras Keras 3 / tf.keras
51
+ ecocode.integrations.onnxruntime ONNX Runtime inference
52
+ """
53
+ from __future__ import annotations
54
+
55
+ from functools import wraps
56
+ from typing import Callable, Optional, TypeVar
57
+
58
+ from ._run import EcoCodeRun
59
+
60
+ __version__ = "1.0.0"
61
+ __all__ = ["run", "track", "EcoCodeRun"]
62
+
63
+ F = TypeVar("F", bound=Callable)
64
+
65
+
66
+ def run(
67
+ name: str = "run",
68
+ *,
69
+ exporter: str = "terminal",
70
+ output_file: Optional[str] = None,
71
+ db_path: Optional[str] = None,
72
+ api_key: Optional[str] = None,
73
+ project_id: Optional[int] = None,
74
+ base_url: Optional[str] = None,
75
+ interval: float = 1.0,
76
+ ) -> EcoCodeRun:
77
+ """
78
+ Return an EcoCodeRun context manager.
79
+
80
+ Parameters
81
+ ----------
82
+ name : str
83
+ Human-readable label for this run.
84
+ exporter : str
85
+ Where to store results:
86
+ - "terminal" (default): print metrics to stdout.
87
+ - "csv": CSV file (requires output_file=).
88
+ - "json": JSON file (requires output_file=).
89
+ - "online": EcoCode platform (requires api_key=).
90
+ output_file : str, optional
91
+ Output path for csv/json exporters.
92
+ db_path : str, optional
93
+ Ignored, with a warning. Accepted only so older call sites keep working.
94
+ api_key : str, optional
95
+ API key for the online exporter. Also read from ECOCODE_API_KEY.
96
+ project_id : int, optional
97
+ Project ID for the online exporter. Inferred from API key if omitted.
98
+ base_url : str, optional
99
+ Ignored (with a warning). The EcoCode backend URL is fixed:
100
+ https://ecocode.harmonyhpc.io
101
+ interval : float
102
+ Sampling interval in seconds (default: 1.0).
103
+
104
+ In attached mode (under `ecocode run`), most parameters are ignored: the
105
+ run was already created by the CLI.
106
+ """
107
+ return EcoCodeRun(
108
+ name,
109
+ exporter=exporter,
110
+ output_file=output_file,
111
+ db_path=db_path,
112
+ api_key=api_key,
113
+ project_id=project_id,
114
+ base_url=base_url,
115
+ interval=interval,
116
+ )
117
+
118
+
119
+ def track(
120
+ name: Optional[str] = None,
121
+ *,
122
+ exporter: str = "terminal",
123
+ output_file: Optional[str] = None,
124
+ db_path: Optional[str] = None,
125
+ api_key: Optional[str] = None,
126
+ project_id: Optional[int] = None,
127
+ base_url: Optional[str] = None,
128
+ interval: float = 1.0,
129
+ ) -> Callable[[F], F]:
130
+ """
131
+ Decorator that wraps a function in an EcoCodeRun context.
132
+
133
+ Usage:
134
+ @ecocode.track(exporter="terminal")
135
+ def train():
136
+ ...
137
+
138
+ @ecocode.track(exporter="online", api_key="eco_...")
139
+ def train():
140
+ ...
141
+ """
142
+ def decorator(fn: F) -> F:
143
+ run_name = name or fn.__name__
144
+
145
+ @wraps(fn)
146
+ def wrapper(*args, **kwargs):
147
+ with EcoCodeRun(
148
+ run_name,
149
+ exporter=exporter,
150
+ output_file=output_file,
151
+ db_path=db_path,
152
+ api_key=api_key,
153
+ project_id=project_id,
154
+ base_url=base_url,
155
+ interval=interval,
156
+ ):
157
+ return fn(*args, **kwargs)
158
+
159
+ return wrapper # type: ignore[return-value]
160
+
161
+ return decorator
ecocode/_binary.py ADDED
@@ -0,0 +1,86 @@
1
+ """Locates the ``ecocode`` CLI binary that runs the energy monitor.
2
+
3
+ The wheel installs the binary into the environment's scripts directory
4
+ (``bin/`` on Linux/macOS, ``Scripts\\`` on Windows), next to ``python``. It is
5
+ looked for there first, then in the user scripts directory
6
+ (``pip install --user``), then on ``PATH``.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ import shutil
13
+ import site
14
+ import sys
15
+ import sysconfig
16
+ import warnings
17
+ from typing import Iterator, Optional
18
+
19
+ EXE_NAME = "ecocode.exe" if os.name == "nt" else "ecocode"
20
+
21
+
22
+ def _scripts_dirs() -> Iterator[str]:
23
+ for scheme in (None, f"{os.name}_user"):
24
+ try:
25
+ path = sysconfig.get_path("scripts", scheme) if scheme else sysconfig.get_path("scripts")
26
+ except KeyError:
27
+ continue
28
+ if path:
29
+ yield path
30
+
31
+
32
+ def _is_executable(path: str) -> bool:
33
+ if not os.path.isfile(path):
34
+ return False
35
+ return os.name == "nt" or os.access(path, os.X_OK)
36
+
37
+
38
+ def find_ecocode_binary() -> Optional[str]:
39
+ """Path of the ecocode binary, or None if it is not installed."""
40
+ for directory in _scripts_dirs():
41
+ candidate = os.path.join(directory, EXE_NAME)
42
+ if _is_executable(candidate):
43
+ return candidate
44
+ found = shutil.which("ecocode")
45
+ return found if found and _is_executable(found) else None
46
+
47
+
48
+ def _trusted_prefixes() -> list[str]:
49
+ """Locations a legitimately installed ecocode binary lives in."""
50
+ prefixes = [sys.prefix, sys.base_prefix, site.getuserbase(), os.path.expanduser("~/.cargo/bin")]
51
+ if os.name == "nt":
52
+ prefixes += [os.environ.get(v, "") for v in ("ProgramFiles", "ProgramFiles(x86)", "LOCALAPPDATA")]
53
+ else:
54
+ prefixes += [os.path.expanduser("~/.local"), "/usr", "/opt", "/bin", "/sbin"]
55
+ return [os.path.normcase(os.path.abspath(p)) for p in prefixes if p]
56
+
57
+
58
+ def _is_under(path: str, prefix: str) -> bool:
59
+ try:
60
+ return os.path.commonpath([path, prefix]) == prefix
61
+ except ValueError: # different drives on Windows
62
+ return False
63
+
64
+
65
+ def resolve_ecocode_binary() -> str:
66
+ """Locate and validate the ecocode CLI binary.
67
+
68
+ Warns when the binary is found outside the expected install locations,
69
+ which can mean an unexpected ``PATH`` entry.
70
+ """
71
+ path = find_ecocode_binary()
72
+ if path is None:
73
+ raise RuntimeError(
74
+ f"[ecocode] The '{EXE_NAME}' monitor binary was not found.\n"
75
+ "It is installed with the SDK: pip install ecocodes\n"
76
+ "When working from a source checkout, build it with `cargo build --release` "
77
+ "and put target/release on your PATH."
78
+ )
79
+ normalized = os.path.normcase(os.path.abspath(path))
80
+ if not any(_is_under(normalized, p) for p in _trusted_prefixes()):
81
+ warnings.warn(
82
+ f"[ecocode] Monitor binary resolved from an unexpected path: '{path}'. "
83
+ "If you did not install EcoCode here, check your PATH for unexpected entries.",
84
+ stacklevel=4,
85
+ )
86
+ return path
ecocode/_http.py ADDED
@@ -0,0 +1,74 @@
1
+ """Thin HTTP client for the EcoCode ingestion API. Uses only stdlib."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import ssl
7
+ import urllib.request
8
+ from typing import Any, Optional
9
+
10
+ # Cap on the response body, so a misbehaving backend cannot exhaust memory.
11
+ _MAX_RESPONSE_BYTES = 1_048_576 # 1 MiB
12
+
13
+ # One strict SSL context (CERT_REQUIRED + check_hostname) shared by every request.
14
+ _SSL_CONTEXT = ssl.create_default_context()
15
+
16
+
17
+ # The EcoCode backend. Fixed on purpose: it cannot be changed by arguments or
18
+ # environment variables, so run data and API keys can't be sent elsewhere by
19
+ # mistake. (Same constant as the CLI's ecocode_api::BASE_URL.)
20
+ BASE_URL = "https://ecocode.harmonyhpc.io"
21
+
22
+
23
+ class EcoCodeHTTPClient:
24
+ """Blocking HTTP client for the ingestion endpoints. Zero external deps."""
25
+
26
+ def __init__(self, api_key: str) -> None:
27
+ self._base_url = BASE_URL.rstrip("/")
28
+ self._headers = {
29
+ "Authorization": f"Bearer {api_key}",
30
+ "Content-Type": "application/json",
31
+ }
32
+
33
+ def _post(self, path: str, body: dict[str, Any]) -> Any:
34
+ url = f"{self._base_url}{path}"
35
+ data = json.dumps(body).encode()
36
+ req = urllib.request.Request(
37
+ url, data=data, headers=self._headers, method="POST"
38
+ )
39
+ # Explicit SSL context so certificate validation is always enforced;
40
+ # the read is capped so a bad backend cannot exhaust memory.
41
+ with urllib.request.urlopen(req, timeout=10, context=_SSL_CONTEXT) as resp:
42
+ if resp.status in (200, 201):
43
+ raw = resp.read(_MAX_RESPONSE_BYTES)
44
+ if raw:
45
+ return json.loads(raw)
46
+ return None
47
+
48
+ def create_run(
49
+ self,
50
+ project_id: int,
51
+ name: str,
52
+ started_at: str,
53
+ command: Optional[str] = None,
54
+ ) -> int:
55
+ resp = self._post(
56
+ "/api/ingest/run",
57
+ {
58
+ "project_id": project_id,
59
+ "name": name,
60
+ "started_at": started_at,
61
+ "command": command,
62
+ "exporter_type": "sdk",
63
+ },
64
+ )
65
+ return resp["id"]
66
+
67
+ def save_system_info(self, run_id: int, info: dict) -> None:
68
+ self._post(f"/api/ingest/run/{run_id}/system-info", info)
69
+
70
+ def complete_run(self, run_id: int, status: str, ended_at: str) -> None:
71
+ self._post(
72
+ f"/api/ingest/run/{run_id}/complete",
73
+ {"status": status, "ended_at": ended_at},
74
+ )
@@ -0,0 +1,90 @@
1
+ """Marker writers: how the SDK sends markers to the ecocode monitor.
2
+
3
+ - Standalone mode: the SDK starts ``ecocode monitor`` and writes to its stdin
4
+ (:class:`PipeWriter`).
5
+ - Attached mode (``ecocode run -- python train.py``): the CLI passes a pipe to
6
+ this process (a file descriptor in ``ECOCODE_MARKER_FD`` on Linux/macOS, a
7
+ handle in ``ECOCODE_MARKER_HANDLE`` on Windows), opened by
8
+ :func:`open_inherited_writer`.
9
+ - Non-zero DDP ranks and inactive runs use :class:`NullWriter`.
10
+
11
+ Every marker is one line of JSON with a ``sent_at_ns`` timestamp.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import json
17
+ import os
18
+ import time
19
+ from typing import IO, Any, Mapping, Optional
20
+
21
+ # Environment variables set by `ecocode run` for the child process.
22
+ MARKER_FD_ENV = "ECOCODE_MARKER_FD"
23
+ MARKER_HANDLE_ENV = "ECOCODE_MARKER_HANDLE"
24
+
25
+
26
+ class PipeWriter:
27
+ """Writes newline-delimited JSON to a binary stream (the monitor's stdin,
28
+ or an inherited pipe). A closed pipe means the monitor exited: markers are
29
+ then dropped silently."""
30
+
31
+ def __init__(self, stream: IO[bytes]) -> None:
32
+ self._stream = stream
33
+
34
+ def send(self, event: dict[str, Any]) -> None:
35
+ try:
36
+ event = {**event, "sent_at_ns": time.time_ns()}
37
+ self._stream.write((json.dumps(event) + "\n").encode())
38
+ self._stream.flush()
39
+ except (BrokenPipeError, OSError, ValueError):
40
+ pass # Monitor exited or stream closed; drop the marker
41
+
42
+ def close(self) -> None:
43
+ try:
44
+ self._stream.close()
45
+ except OSError:
46
+ pass
47
+
48
+
49
+ class NullWriter:
50
+ """No-op writer for DDP non-zero ranks or pre-enter state."""
51
+
52
+ def send(self, event: dict[str, Any]) -> None:
53
+ pass
54
+
55
+ def close(self) -> None:
56
+ pass
57
+
58
+
59
+ def marker_pipe_in(env: Mapping[str, str]) -> bool:
60
+ """Whether ``env`` carries a marker pipe from ``ecocode run``."""
61
+ key = MARKER_HANDLE_ENV if os.name == "nt" else MARKER_FD_ENV
62
+ return bool(env.get(key))
63
+
64
+
65
+ def open_inherited_writer(env: Mapping[str, str]) -> Optional[PipeWriter]:
66
+ """Opens the marker pipe passed by ``ecocode run``, or returns None if
67
+ there is none. Raises ValueError if the variable is set but invalid."""
68
+ if os.name == "nt":
69
+ raw = env.get(MARKER_HANDLE_ENV)
70
+ if not raw:
71
+ return None
72
+ from .windows import open_marker_handle
73
+
74
+ return PipeWriter(open_marker_handle(raw))
75
+ raw = env.get(MARKER_FD_ENV)
76
+ if not raw:
77
+ return None
78
+ from .posix import open_marker_fd
79
+
80
+ return PipeWriter(open_marker_fd(raw))
81
+
82
+
83
+ __all__ = [
84
+ "MARKER_FD_ENV",
85
+ "MARKER_HANDLE_ENV",
86
+ "NullWriter",
87
+ "PipeWriter",
88
+ "marker_pipe_in",
89
+ "open_inherited_writer",
90
+ ]
ecocode/_pipe/posix.py ADDED
@@ -0,0 +1,18 @@
1
+ """Linux and macOS: the marker pipe is an inherited file descriptor."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from typing import IO
7
+
8
+ from .._validation import validate_marker_fd
9
+
10
+
11
+ def open_marker_fd(raw: str) -> IO[bytes]:
12
+ """Opens the descriptor named by ``ECOCODE_MARKER_FD`` for writing.
13
+
14
+ The value is validated first: it must be > 2 and open in this
15
+ process, so a tampered value cannot redirect markers to stdout.
16
+ """
17
+ fd = validate_marker_fd(raw)
18
+ return os.fdopen(fd, "wb", closefd=True)
@@ -0,0 +1,24 @@
1
+ """Windows: the marker pipe is an inherited handle."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from typing import IO
7
+
8
+ from .._validation import validate_marker_handle
9
+
10
+
11
+ def open_marker_handle(raw: str) -> IO[bytes]:
12
+ """Opens the handle named by ``ECOCODE_MARKER_HANDLE`` for writing.
13
+
14
+ ``msvcrt.open_osfhandle`` wraps the inherited Win32 handle in a C runtime
15
+ descriptor; closing the returned file closes the handle.
16
+ """
17
+ import msvcrt
18
+
19
+ handle = validate_marker_handle(raw)
20
+ try:
21
+ fd = msvcrt.open_osfhandle(handle, os.O_WRONLY)
22
+ except OSError as exc:
23
+ raise ValueError(f"ECOCODE_MARKER_HANDLE={handle} is not an open handle: {exc}") from exc
24
+ return os.fdopen(fd, "wb", closefd=True)