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/_run.py ADDED
@@ -0,0 +1,400 @@
1
+ """The ``EcoCodeRun`` class behind ``ecocode.run()`` and ``ecocode.track()``.
2
+
3
+ A run can be used as a context manager, as a decorator, or with explicit
4
+ ``start()`` / ``stop()`` calls:
5
+
6
+ with ecocode.run("name", exporter="terminal") as run: ...
7
+
8
+ @ecocode.track("name", exporter="terminal")
9
+ def train(): ...
10
+
11
+ run = ecocode.run("name", exporter="terminal")
12
+ run.start()
13
+ ...
14
+ run.stop()
15
+
16
+ Exporters: ``terminal`` (default) prints metrics to stdout; ``csv``, ``json``
17
+ and ``logfile`` write records to ``output_file``. None of these need an API
18
+ key or the network. ``online`` sends records to https://ecocode.harmonyhpc.io
19
+ and requires ``api_key`` (or ``ECOCODE_API_KEY``).
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import os
25
+ import subprocess
26
+ import sys
27
+ import warnings
28
+ from datetime import datetime, timezone
29
+ from typing import Any, Optional
30
+
31
+ from ._binary import resolve_ecocode_binary
32
+ from ._http import BASE_URL, EcoCodeHTTPClient
33
+ from ._pipe import NullWriter, PipeWriter, marker_pipe_in, open_inherited_writer
34
+ from ._sysinfo import collect_system_info
35
+ from ._validation import validate_api_key, validate_run_id
36
+
37
+ # Only the environment variables the monitor subprocess needs are forwarded.
38
+ # Passing the whole parent environment would expose every secret in it to the
39
+ # child (visible via /proc/<pid>/environ on Linux).
40
+ _SUBPROCESS_ENV_PASSTHROUGH = frozenset({
41
+ # Shell / runtime essentials
42
+ "PATH", "HOME", "USER", "LOGNAME", "SHELL",
43
+ "LANG", "LC_ALL", "LC_CTYPE", "LANGUAGE",
44
+ "TMPDIR", "TMP", "TEMP",
45
+ "XDG_RUNTIME_DIR", "XDG_DATA_DIRS",
46
+ # Windows essentials (process creation, home directory, DLL lookup)
47
+ "SYSTEMDRIVE", "WINDIR", "COMSPEC", "PATHEXT",
48
+ "USERPROFILE", "APPDATA", "LOCALAPPDATA", "PROGRAMDATA",
49
+ "PROGRAMFILES", "PROGRAMFILES(X86)", "NUMBER_OF_PROCESSORS",
50
+ # EcoCode test hook: fake sensors for runs on machines without hardware
51
+ "ECOCODE_SENSORS",
52
+ # Dynamic linker, needed for native extensions
53
+ "LD_LIBRARY_PATH", "LD_PRELOAD",
54
+ "DYLD_LIBRARY_PATH", "DYLD_FALLBACK_LIBRARY_PATH", # macOS
55
+ # NVIDIA / CUDA
56
+ "CUDA_VISIBLE_DEVICES", "CUDA_HOME", "CUDA_PATH",
57
+ "NVML_LIBRARY_PATH", "NVIDIA_VISIBLE_DEVICES",
58
+ # AMD ROCm
59
+ "ROCR_VISIBLE_DEVICES", "HIP_VISIBLE_DEVICES", "HSA_OVERRIDE_GFX_VERSION",
60
+ # Intel oneAPI
61
+ "ONEAPI_DEVICE_SELECTOR", "ZE_AFFINITY_MASK",
62
+ # System hardware detection
63
+ "SYSTEM_ROOT", "SYSTEMROOT",
64
+ })
65
+
66
+ # Exporters that are handled entirely locally (no API key, no network).
67
+ _LOCAL_EXPORTERS = frozenset({"terminal", "csv", "json", "logfile"})
68
+
69
+
70
+ class EcoCodeRun:
71
+ """Context manager for tracking an ML run's energy and semantic markers."""
72
+
73
+ def __init__(
74
+ self,
75
+ name: str,
76
+ *,
77
+ exporter: str = "terminal",
78
+ output_file: Optional[str] = None,
79
+ db_path: Optional[str] = None,
80
+ api_key: Optional[str] = None,
81
+ project_id: Optional[int] = None,
82
+ base_url: Optional[str] = None,
83
+ interval: float = 1.0,
84
+ ) -> None:
85
+ self._name = name
86
+ self._exporter = exporter.lower().strip()
87
+ if self._exporter in ("local", "sqlite"):
88
+ warnings.warn(
89
+ "[ecocode] The 'local' exporter was removed; using 'terminal' instead.",
90
+ UserWarning,
91
+ stacklevel=2,
92
+ )
93
+ self._exporter = "terminal"
94
+
95
+ if db_path:
96
+ warnings.warn(
97
+ "[ecocode] 'db_path' is ignored: it belonged to the 'local' exporter, which was removed.",
98
+ UserWarning,
99
+ stacklevel=2,
100
+ )
101
+
102
+ self._output_file = output_file
103
+ self._db_path = None
104
+ self._project_id = project_id
105
+ self._interval = interval
106
+ self._run_id: Optional[int] = None
107
+ self._monitor_proc: Optional[subprocess.Popen] = None
108
+ self._pipe: PipeWriter = NullWriter()
109
+ self._client: Optional[EcoCodeHTTPClient] = None
110
+ self._mode: str = "unknown"
111
+
112
+ if base_url is not None or os.environ.get("ECOCODE_API_URL"):
113
+ warnings.warn(
114
+ f"[ecocode] base_url / ECOCODE_API_URL is ignored: the EcoCode backend is fixed "
115
+ f"({BASE_URL}).",
116
+ UserWarning,
117
+ stacklevel=3,
118
+ )
119
+
120
+ if self._exporter == "online":
121
+ # Resolve the API key from arguments then environment, and validate it
122
+ # eagerly so misconfiguration fails at construction time rather than at
123
+ # the first network call.
124
+ raw_key = api_key or os.environ.get("ECOCODE_API_KEY")
125
+ self._api_key: Optional[str] = validate_api_key(raw_key) if raw_key else None
126
+ else:
127
+ # Local exporters never touch the network.
128
+ self._api_key = None
129
+
130
+ # Validate exporter-specific arguments early.
131
+ if self._exporter in ("csv", "json", "logfile") and not self._output_file:
132
+ raise ValueError(
133
+ f"[ecocode] output_file is required when using exporter='{self._exporter}'."
134
+ )
135
+
136
+ def __enter__(self) -> EcoCodeRun:
137
+ # DDP rank detection: only track on rank 0
138
+ rank = os.environ.get("RANK") or os.environ.get("LOCAL_RANK")
139
+ if rank is not None and int(rank) != 0:
140
+ self._mode = "noop"
141
+ return self
142
+
143
+ # Attached mode: `ecocode run` already created the run and passed a
144
+ # marker pipe (a file descriptor on Linux/macOS, a handle on Windows).
145
+ env_run_id = os.environ.get("ECOCODE_RUN_ID")
146
+
147
+ if env_run_id and marker_pipe_in(os.environ):
148
+ self._mode = "attached"
149
+
150
+ # Check the run ID is a sane positive integer rather than blindly
151
+ # casting whatever the env var contains.
152
+ try:
153
+ self._run_id = validate_run_id(env_run_id)
154
+ except ValueError as exc:
155
+ raise ValueError(
156
+ f"[ecocode] Invalid ECOCODE_RUN_ID: {exc}"
157
+ ) from exc
158
+
159
+ # The inherited FD/handle is validated before it is opened. A
160
+ # tampered ECOCODE_MARKER_FD=1 would otherwise redirect all marker
161
+ # writes to stdout.
162
+ try:
163
+ self._pipe = open_inherited_writer(os.environ) or NullWriter()
164
+ except ValueError as exc:
165
+ warnings.warn(
166
+ f"[ecocode] Ignoring invalid marker pipe: {exc}. "
167
+ "Phase markers will not be recorded for this run.",
168
+ stacklevel=3,
169
+ )
170
+ self._pipe = NullWriter()
171
+
172
+ return self
173
+
174
+ # Standalone mode: branch on exporter type.
175
+ if self._exporter in _LOCAL_EXPORTERS:
176
+ return self._start_local_standalone()
177
+ else:
178
+ return self._start_online_standalone()
179
+
180
+ def _start_local_standalone(self) -> EcoCodeRun:
181
+ """Start a standalone run with a local exporter (no API key needed)."""
182
+ ecocode_bin = resolve_ecocode_binary()
183
+
184
+ # Build safe environment for the subprocess.
185
+ safe_env: dict[str, str] = {
186
+ k: v
187
+ for k, v in os.environ.items()
188
+ if k in _SUBPROCESS_ENV_PASSTHROUGH
189
+ }
190
+
191
+ # `ecocode monitor-local` writes locally, no network calls. Run ID 0 is
192
+ # a placeholder; the monitor subprocess manages the run itself.
193
+ self._run_id = 0
194
+ self._mode = "standalone_local"
195
+
196
+ cmd = [
197
+ ecocode_bin,
198
+ "monitor-local",
199
+ "--run-id", str(self._run_id),
200
+ "--pid", str(os.getpid()),
201
+ "--interval", str(self._interval),
202
+ "--exporter", self._exporter,
203
+ ]
204
+ if self._output_file:
205
+ cmd += ["--file", self._output_file]
206
+
207
+ self._monitor_proc = subprocess.Popen(
208
+ cmd,
209
+ stdin=subprocess.PIPE,
210
+ stdout=None if self._exporter == "terminal" else subprocess.DEVNULL,
211
+ stderr=subprocess.DEVNULL,
212
+ env=safe_env,
213
+ )
214
+
215
+ import time as _time
216
+ _time.sleep(0.2)
217
+ rc = self._monitor_proc.poll()
218
+ if rc is not None:
219
+ raise RuntimeError(
220
+ f"[ecocode] monitor-local subprocess exited immediately (code {rc}).\n"
221
+ "Check that the ecocode binary is installed and the exporter path is writable."
222
+ )
223
+
224
+ self._pipe = PipeWriter(self._monitor_proc.stdin)
225
+ return self
226
+
227
+ def _start_online_standalone(self) -> EcoCodeRun:
228
+ """Start a standalone run posting records to the EcoCode online platform."""
229
+ if not self._api_key:
230
+ raise ValueError(
231
+ "api_key is required when using exporter='online' in standalone mode. "
232
+ "Pass api_key= or set ECOCODE_API_KEY."
233
+ )
234
+
235
+ self._client = EcoCodeHTTPClient(self._api_key)
236
+ started_at = datetime.now(timezone.utc).isoformat()
237
+ command = _sanitize_command(sys.argv) if hasattr(sys, "argv") and sys.argv else None
238
+
239
+ try:
240
+ self._run_id = self._client.create_run(
241
+ project_id=self._project_id or 0,
242
+ name=self._name,
243
+ started_at=started_at,
244
+ command=command,
245
+ )
246
+ self._client.save_system_info(self._run_id, collect_system_info())
247
+ except Exception as exc:
248
+ warnings.warn(
249
+ f"[ecocode] EcoCode backend unreachable or failed to initialize run: {exc}. "
250
+ "Running in local fallback mode.",
251
+ category=UserWarning,
252
+ stacklevel=3,
253
+ )
254
+ self._mode = "noop"
255
+ return self
256
+
257
+ ecocode_bin = resolve_ecocode_binary()
258
+
259
+ # Build a minimal environment for the monitor subprocess.
260
+ safe_env: dict[str, str] = {
261
+ k: v
262
+ for k, v in os.environ.items()
263
+ if k in _SUBPROCESS_ENV_PASSTHROUGH
264
+ }
265
+ safe_env["ECOCODE_API_KEY"] = self._api_key # type: ignore[assignment]
266
+
267
+ self._mode = "standalone_online"
268
+ self._monitor_proc = subprocess.Popen(
269
+ [
270
+ ecocode_bin,
271
+ "monitor",
272
+ "--run-id",
273
+ str(self._run_id),
274
+ "--pid",
275
+ str(os.getpid()),
276
+ "--interval",
277
+ str(self._interval),
278
+ ],
279
+ stdin=subprocess.PIPE,
280
+ stdout=subprocess.DEVNULL,
281
+ stderr=subprocess.DEVNULL,
282
+ env=safe_env,
283
+ )
284
+
285
+ import time as _time
286
+ _time.sleep(0.2)
287
+ rc = self._monitor_proc.poll()
288
+ if rc is not None:
289
+ raise RuntimeError(
290
+ f"[ecocode] monitor subprocess exited immediately (code {rc}).\n"
291
+ "Check that ECOCODE_API_KEY is valid and the backend is reachable."
292
+ )
293
+
294
+ self._pipe = PipeWriter(self._monitor_proc.stdin)
295
+ return self
296
+
297
+ def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
298
+ if self._mode == "noop":
299
+ return False
300
+
301
+ self._pipe.close()
302
+
303
+ if self._monitor_proc is not None:
304
+ try:
305
+ self._monitor_proc.wait(timeout=10)
306
+ except subprocess.TimeoutExpired:
307
+ self._monitor_proc.kill()
308
+ self._monitor_proc.wait()
309
+
310
+ if self._mode == "standalone_online" and self._client and self._run_id:
311
+ status = "failed" if exc_type else "finished"
312
+ ended_at = datetime.now(timezone.utc).isoformat()
313
+ try:
314
+ self._client.complete_run(self._run_id, status, ended_at)
315
+ except Exception:
316
+ pass # Don't mask the original exception
317
+
318
+ return False # Never suppress exceptions
319
+
320
+ def start(self) -> EcoCodeRun:
321
+ """Begin tracking. Alternative to using as a context manager."""
322
+ return self.__enter__()
323
+
324
+ def stop(self) -> None:
325
+ """Stop tracking and finalize the run. Alternative to context manager exit."""
326
+ self.__exit__(None, None, None)
327
+
328
+ def mark(self, key: str, value: Any) -> None:
329
+ self._pipe.send({"event": str(key), "value": str(value)})
330
+
331
+ def log_epoch(self, epoch: int) -> None:
332
+ self._pipe.send({"event": "epoch", "value": epoch})
333
+
334
+ def log_step(self, step: int) -> None:
335
+ self._pipe.send({"event": "step", "value": step})
336
+
337
+ def log_tokens(self, count: int) -> None:
338
+ self._pipe.send({"event": "tokens", "count": count})
339
+
340
+ def log_loss(self, loss: float) -> None:
341
+ self._pipe.send({"event": "loss", "value": loss})
342
+
343
+ def log_lr(self, lr: float) -> None:
344
+ self._pipe.send({"event": "learning_rate", "value": lr})
345
+
346
+ def log_sequence_length(self, seq_len: int) -> None:
347
+ self._pipe.send({"event": "sequence_length", "value": seq_len})
348
+
349
+ def log_accuracy(self, accuracy: float) -> None:
350
+ self._pipe.send({"event": "accuracy", "value": accuracy})
351
+
352
+ def log_custom(self, key: str, value: float) -> None:
353
+ self._pipe.send({"event": "custom", "key": key, "value": value})
354
+
355
+
356
+ # Flag names whose next value is a secret. Keep this set lower-cased;
357
+ # matching is done case-insensitively.
358
+ _SENSITIVE_FLAG_NAMES: frozenset[str] = frozenset({
359
+ # EcoCode / generic auth
360
+ "--api-key", "--api_key", "--token", "-k", "-t",
361
+ # HuggingFace
362
+ "--hf-token", "--hf_token", "--huggingface-token", "--huggingface_token",
363
+ # Weights & Biases
364
+ "--wandb-key", "--wandb_key", "--wandb-api-key",
365
+ # OpenAI / generic LLM providers
366
+ "--openai-key", "--openai_key", "--openai-api-key", "--openai_api_key",
367
+ # Generic secret/password flags
368
+ "--password", "--passwd", "--secret",
369
+ "--access-token", "--access_token",
370
+ "--auth-token", "--auth_token",
371
+ "--bearer", "--private-key", "--private_key",
372
+ "--credentials", "--key",
373
+ })
374
+
375
+
376
+ def _sanitize_command(args: list[str]) -> str:
377
+ """Redact the values of known secret flags (API keys, tokens) from sys.argv
378
+ so they never reach the backend in the run's 'command' field."""
379
+ sanitized = []
380
+ skip_next = False
381
+ for i, arg in enumerate(args):
382
+ if skip_next:
383
+ skip_next = False
384
+ continue
385
+
386
+ if "=" in arg:
387
+ key, val = arg.split("=", 1)
388
+ if key.lower() in _SENSITIVE_FLAG_NAMES:
389
+ sanitized.append(f"{key}=********")
390
+ else:
391
+ sanitized.append(arg)
392
+ elif arg.lower() in _SENSITIVE_FLAG_NAMES:
393
+ sanitized.append(arg)
394
+ if i + 1 < len(args):
395
+ sanitized.append("********")
396
+ skip_next = True
397
+ else:
398
+ sanitized.append(arg)
399
+
400
+ return " ".join(sanitized)
ecocode/_sysinfo.py ADDED
@@ -0,0 +1,133 @@
1
+ """Hardware summary sent once per run (online standalone mode), using only the
2
+ standard library on Linux, macOS and Windows."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import ctypes
7
+ import os
8
+ import platform
9
+ import shutil
10
+ import subprocess
11
+ import sys
12
+ from typing import Optional
13
+
14
+
15
+ def _linux_cpu_name() -> Optional[str]:
16
+ try:
17
+ with open("/proc/cpuinfo") as f:
18
+ for i, line in enumerate(f):
19
+ if i > 200: # don't read an unbounded file
20
+ break
21
+ if line.lower().startswith("model name"):
22
+ return line.split(":", 1)[1].strip()
23
+ except OSError:
24
+ pass
25
+ return None
26
+
27
+
28
+ def _linux_ram_bytes() -> Optional[int]:
29
+ try:
30
+ with open("/proc/meminfo") as f:
31
+ # The real file has about 50 lines; stop past that.
32
+ for i, line in enumerate(f):
33
+ if i >= 60:
34
+ break
35
+ if line.startswith("MemTotal:"):
36
+ parts = line.split()
37
+ if len(parts) >= 2 and parts[1].isdigit():
38
+ return int(parts[1]) * 1024
39
+ except OSError:
40
+ pass
41
+ return None
42
+
43
+
44
+ def _sysctl(name: str, kind: str) -> object:
45
+ """Reads a macOS sysctl as "u64" or "str" without spawning a process."""
46
+ libc = ctypes.CDLL(None)
47
+ size = ctypes.c_size_t(0)
48
+ if libc.sysctlbyname(name.encode(), None, ctypes.byref(size), None, 0) != 0 or size.value == 0:
49
+ return None
50
+ buf = ctypes.create_string_buffer(size.value)
51
+ if libc.sysctlbyname(name.encode(), buf, ctypes.byref(size), None, 0) != 0:
52
+ return None
53
+ if kind == "u64":
54
+ return int.from_bytes(buf.raw[: size.value], sys.byteorder)
55
+ return buf.value.decode(errors="replace").strip() or None
56
+
57
+
58
+ def _windows_cpu_name() -> Optional[str]:
59
+ try:
60
+ import winreg
61
+
62
+ key = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, r"HARDWARE\DESCRIPTION\System\CentralProcessor\0")
63
+ value, _ = winreg.QueryValueEx(key, "ProcessorNameString")
64
+ return str(value).strip()
65
+ except OSError:
66
+ return None
67
+
68
+
69
+ def _windows_ram_bytes() -> Optional[int]:
70
+ class MEMORYSTATUSEX(ctypes.Structure):
71
+ _fields_ = [
72
+ ("dwLength", ctypes.c_ulong),
73
+ ("dwMemoryLoad", ctypes.c_ulong),
74
+ ("ullTotalPhys", ctypes.c_ulonglong),
75
+ ("ullAvailPhys", ctypes.c_ulonglong),
76
+ ("ullTotalPageFile", ctypes.c_ulonglong),
77
+ ("ullAvailPageFile", ctypes.c_ulonglong),
78
+ ("ullTotalVirtual", ctypes.c_ulonglong),
79
+ ("ullAvailVirtual", ctypes.c_ulonglong),
80
+ ("ullAvailExtendedVirtual", ctypes.c_ulonglong),
81
+ ]
82
+
83
+ status = MEMORYSTATUSEX()
84
+ status.dwLength = ctypes.sizeof(MEMORYSTATUSEX)
85
+ if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(status)): # type: ignore[attr-defined]
86
+ return int(status.ullTotalPhys)
87
+ return None
88
+
89
+
90
+ def _nvidia_gpus() -> list[str]:
91
+ nvidia_smi = shutil.which("nvidia-smi")
92
+ if not nvidia_smi:
93
+ return []
94
+ try:
95
+ res = subprocess.run(
96
+ [nvidia_smi, "--query-gpu=name", "--format=csv,noheader"],
97
+ capture_output=True,
98
+ text=True,
99
+ check=False,
100
+ timeout=5,
101
+ )
102
+ except (OSError, subprocess.SubprocessError):
103
+ return []
104
+ if res.returncode != 0:
105
+ return []
106
+ return [line.strip() for line in res.stdout.splitlines() if line.strip()]
107
+
108
+
109
+ def collect_system_info() -> dict:
110
+ """CPU, core count, RAM and GPUs, in the backend's system-info format."""
111
+ cpu_name: Optional[str] = None
112
+ ram: Optional[int] = None
113
+ gpus = _nvidia_gpus()
114
+ try:
115
+ if sys.platform.startswith("linux"):
116
+ cpu_name, ram = _linux_cpu_name(), _linux_ram_bytes()
117
+ elif sys.platform == "darwin":
118
+ cpu_name = _sysctl("machdep.cpu.brand_string", "str") # type: ignore[assignment]
119
+ ram = _sysctl("hw.memsize", "u64") # type: ignore[assignment]
120
+ # Apple Silicon's GPU is part of the chip; the CLI reports it as GPU 0.
121
+ if not gpus and _sysctl("hw.optional.arm64", "u64") == 1 and cpu_name:
122
+ gpus = [f"{cpu_name} GPU"]
123
+ elif os.name == "nt":
124
+ cpu_name, ram = _windows_cpu_name(), _windows_ram_bytes()
125
+ except Exception:
126
+ pass
127
+ return {
128
+ "cpu_name": cpu_name or platform.processor() or platform.machine() or "Unknown",
129
+ "cpu_cores": os.cpu_count() or 0,
130
+ "ram_gb": round(ram / 1_073_741_824, 1) if ram else 0.0,
131
+ "gpu_count": len(gpus),
132
+ "gpu_names": ", ".join(gpus),
133
+ }
ecocode/_validation.py ADDED
@@ -0,0 +1,148 @@
1
+ """Validators for the values the SDK reads from arguments and the environment:
2
+ API keys, run IDs, marker pipe descriptors and custom metric keys.
3
+
4
+ Each one raises ``ValueError`` with a clear message, so a misconfigured
5
+ environment fails loudly instead of forwarding bad credentials or corrupted
6
+ data to the backend.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ import re
13
+
14
+ _API_KEY_RE = re.compile(r"^(?:eco|ecocode)_[A-Za-z0-9_\-]{8,240}$")
15
+ _CTRL_CHARS_RE = re.compile(r"[\x00-\x1f\x7f]")
16
+
17
+
18
+ def validate_api_key(key: str) -> str:
19
+ """Validate and return *key*.
20
+
21
+ Must be non-empty, start with ``eco_`` or ``ecocode_``, contain only
22
+ alphanumerics/underscore/hyphen after the prefix, have no control chars
23
+ (blocks header injection), and be 12-248 characters total. Raises
24
+ ValueError otherwise.
25
+ """
26
+ if not isinstance(key, str) or not key:
27
+ raise ValueError(
28
+ "ECOCODE_API_KEY must be a non-empty string. "
29
+ "Generate a key from the EcoCode dashboard."
30
+ )
31
+ if _CTRL_CHARS_RE.search(key):
32
+ raise ValueError(
33
+ "ECOCODE_API_KEY contains control characters and will be rejected. "
34
+ "Check that the key was not corrupted when reading from the environment."
35
+ )
36
+ if not _API_KEY_RE.match(key):
37
+ raise ValueError(
38
+ f"ECOCODE_API_KEY does not match the expected format (ecocode_<token> or eco_<token>). "
39
+ f"Received a key starting with: {key[:12]!r}... "
40
+ "Generate a valid key from the EcoCode dashboard."
41
+ )
42
+ return key
43
+
44
+
45
+ _RUN_ID_MAX = 2 ** 53 # JavaScript-safe integer boundary (matches most backends)
46
+
47
+
48
+ def validate_run_id(raw: str) -> int:
49
+ """Parse and validate the ``ECOCODE_RUN_ID`` environment variable.
50
+
51
+ Must be a base-10 integer, >= 1, and <= 2**53 (JavaScript-safe integer
52
+ boundary). Raises ValueError otherwise.
53
+ """
54
+ try:
55
+ run_id = int(raw, 10)
56
+ except (ValueError, TypeError):
57
+ raise ValueError(
58
+ f"ECOCODE_RUN_ID must be a positive integer, got: {raw!r}"
59
+ )
60
+
61
+ if run_id < 1:
62
+ raise ValueError(
63
+ f"ECOCODE_RUN_ID must be >= 1, got: {run_id}. "
64
+ "A run ID of 0 or negative is not valid."
65
+ )
66
+
67
+ if run_id > _RUN_ID_MAX:
68
+ raise ValueError(
69
+ f"ECOCODE_RUN_ID {run_id} exceeds the maximum allowed value "
70
+ f"({_RUN_ID_MAX}). The value may have been corrupted."
71
+ )
72
+
73
+ return run_id
74
+
75
+
76
+ def validate_marker_fd(raw: str) -> int:
77
+ """Parse and validate the ``ECOCODE_MARKER_FD`` environment variable.
78
+
79
+ Must be a base-10 integer, > 2 (not stdin=0/stdout=1/stderr=2), and an FD
80
+ that's actually open in this process (checked via ``os.fstat``). Raises
81
+ ValueError otherwise.
82
+ """
83
+ try:
84
+ fd = int(raw, 10)
85
+ except (ValueError, TypeError):
86
+ raise ValueError(
87
+ f"ECOCODE_MARKER_FD must be an integer file descriptor, got: {raw!r}"
88
+ )
89
+
90
+ if fd <= 2:
91
+ raise ValueError(
92
+ f"ECOCODE_MARKER_FD={fd} is not allowed. "
93
+ "FD 0 (stdin), 1 (stdout), and 2 (stderr) are reserved and must not "
94
+ "be used as a marker pipe. The CLI should pass a dedicated write-only FD."
95
+ )
96
+
97
+ try:
98
+ os.fstat(fd)
99
+ except OSError:
100
+ raise ValueError(
101
+ f"ECOCODE_MARKER_FD={fd} is not a valid open file descriptor in this "
102
+ "process. The FD may have been closed or the environment variable may "
103
+ "have been tampered with."
104
+ )
105
+
106
+ return fd
107
+
108
+
109
+ _HANDLE_MAX = 2 ** 63 - 1
110
+
111
+
112
+ def validate_marker_handle(raw: str) -> int:
113
+ """Parse and validate the ``ECOCODE_MARKER_HANDLE`` environment variable.
114
+
115
+ On Windows the CLI passes the marker pipe as an inherited handle value.
116
+ Must be a positive base-10 integer. Whether it is an open handle is checked
117
+ when it is opened (``msvcrt.open_osfhandle``). Raises ValueError otherwise.
118
+ """
119
+ try:
120
+ handle = int(raw, 10)
121
+ except (ValueError, TypeError):
122
+ raise ValueError(
123
+ f"ECOCODE_MARKER_HANDLE must be an integer handle value, got: {raw!r}"
124
+ )
125
+ if not 0 < handle <= _HANDLE_MAX:
126
+ raise ValueError(f"ECOCODE_MARKER_HANDLE={handle} is out of range.")
127
+ return handle
128
+
129
+
130
+ _METRIC_KEY_RE = re.compile(r"^[A-Za-z0-9_\-]{1,128}$")
131
+
132
+
133
+ def validate_metric_key(key: str) -> str:
134
+ """Validate a custom metric key before forwarding it to the backend.
135
+
136
+ Must be non-empty, alphanumeric/underscore/hyphen only, and at most 128
137
+ characters. Raises ValueError otherwise.
138
+ """
139
+ if not isinstance(key, str) or not key:
140
+ raise ValueError("Metric key must be a non-empty string.")
141
+
142
+ if not _METRIC_KEY_RE.match(key):
143
+ raise ValueError(
144
+ f"Metric key {key!r} contains invalid characters or exceeds 128 chars. "
145
+ "Only alphanumeric characters, underscores, and hyphens are allowed."
146
+ )
147
+
148
+ return key
@@ -0,0 +1,10 @@
1
+ # Integrations are imported lazily to avoid hard dependencies at top level.
2
+ # Import the integration you need explicitly:
3
+ #
4
+ # from ecocode.integrations.huggingface import EcoCodeCallback
5
+ # from ecocode.integrations.trl import EcoCodeSFTCallback, EcoCodeDPOCallback, EcoCodeGRPOCallback
6
+ # from ecocode.integrations.lightning import EcoCodeCallback
7
+ # from ecocode.integrations.deepspeed import EcoCodeDeepSpeedCallback
8
+ # from ecocode.integrations.vllm import EcoCodeVLLMMiddleware
9
+ # from ecocode.integrations.keras import EcoCodeCallback # Keras 3 / tf.keras
10
+ # from ecocode.integrations.onnxruntime import EcoCodeORTWrapper # ONNX Runtime inference