netlab 0.6.1__py3-none-any.whl

netlab/__init__.py

@@ -0,0 +1,10 @@
+"""NetLab: metrics and experiment tooling for NetGraph scenarios."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("netlab")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev"  # Package metadata is unavailable before installation.
+
+__all__ = ["__version__"]

netlab/artifacts.py

@@ -0,0 +1,152 @@
+"""Atomic artifact publication and content-based provenance."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from contextlib import contextmanager
+from importlib.metadata import distribution
+from importlib.util import find_spec
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any, Iterator
+
+
+@contextmanager
+def atomic_path(path: Path) -> Iterator[Path]:
+    """Publish a same-filesystem temporary file only after a successful write."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with NamedTemporaryFile(
+        dir=path.parent, prefix=f".{path.name}.", delete=False
+    ) as f:
+        temporary = Path(f.name)
+    try:
+        yield temporary
+        temporary.replace(path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def write_text_atomic(path: Path, content: str) -> None:
+    with atomic_path(path) as temporary:
+        temporary.write_text(content, encoding="utf-8")
+
+
+def write_json_atomic(path: Path, data: Any) -> None:
+    write_text_atomic(path, json.dumps(data, indent=2) + "\n")
+
+
+def write_csv_atomic(path: Path, data: Any) -> None:
+    import pandas as pd
+
+    table = data if isinstance(data, (pd.DataFrame, pd.Series)) else pd.DataFrame(data)
+    with atomic_path(path) as temporary:
+        table.to_csv(temporary)
+
+
+def sha256_file(path: Path) -> str:
+    with path.open("rb") as stream:
+        return hashlib.file_digest(stream, "sha256").hexdigest()
+
+
+def fingerprint(data: Any) -> str:
+    return hashlib.sha256(json.dumps(data, sort_keys=True).encode()).hexdigest()
+
+
+def package_versions() -> dict[str, dict[str, Any]]:
+    """Identify installed revisions, including current editable package contents."""
+    packages = {}
+    for name in ("netlab", "netlab-topogen", "ngraph", "netgraph-core"):
+        package = distribution(name)
+        record: dict[str, Any] = {"version": package.version}
+        direct_url = package.read_text("direct_url.json")
+        if direct_url:
+            record["source"] = json.loads(direct_url)
+            if record["source"].get("dir_info", {}).get("editable"):
+                spec = find_spec(name.replace("-", "_"))
+                if spec is None or not spec.submodule_search_locations:
+                    raise ValueError(f"Cannot fingerprint editable package {name}")
+                files = {}
+                for location in spec.submodule_search_locations:
+                    root = Path(location)
+                    for path in sorted(root.rglob("*")):
+                        if path.is_file() and path.suffix in {".py", ".so", ".pyd"}:
+                            files[str(path.relative_to(root))] = sha256_file(path)
+                record["content_sha256"] = fingerprint(files)
+        packages[name] = record
+    return packages
+
+
+def package_provenance() -> dict[str, dict[str, Any]]:
+    """Record verified Git or pip VCS identity without local URLs, and use null for unknown Git state."""
+    packages = package_versions()
+    netlab = packages["netlab"]
+    source = netlab.pop("source", {})
+    commit = None
+    dirty = None
+    root = Path(__file__).resolve().parents[1]
+    if (root / ".git").exists():
+        try:
+            status = subprocess.run(
+                [
+                    "git",
+                    "--no-optional-locks",
+                    "status",
+                    "--porcelain",
+                    "--untracked-files=normal",
+                    "--ignore-submodules=none",
+                ],
+                cwd=root,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            dirty = bool(status.stdout)
+            if not dirty:
+                commit = subprocess.run(
+                    ["git", "rev-parse", "HEAD"],
+                    cwd=root,
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                ).stdout.strip()
+        except (subprocess.CalledProcessError, OSError):
+            commit = dirty = None
+    elif installed_commit := source.get("vcs_info", {}).get("commit_id"):
+        commit = installed_commit
+        dirty = False
+    netlab.update(commit=commit, dirty=dirty)
+    return packages
+
+
+def ensure_run_identity(path: Path, inputs: Any) -> None:
+    """Bind a resumable output directory to exactly one set of inputs."""
+    key = fingerprint(inputs)
+    if path.exists():
+        previous = json.loads(path.read_text(encoding="utf-8"))
+        if previous["key"] != key:
+            raise ValueError(
+                f"Research inputs or dependencies changed: {path}. "
+                "Use a new output directory for this experiment."
+            )
+    else:
+        write_json_atomic(path, {"key": key, "inputs": inputs})
+
+
+def cache_path(artifact: Path) -> Path:
+    return artifact.with_suffix(artifact.suffix + ".cache.json")
+
+
+def cache_matches(artifact: Path, key: str) -> bool:
+    try:
+        manifest = json.loads(cache_path(artifact).read_text(encoding="utf-8"))
+        return manifest["key"] == key and manifest["sha256"] == sha256_file(artifact)
+    except (OSError, ValueError, KeyError, TypeError):
+        return False
+
+
+def record_cache(artifact: Path, key: str) -> None:
+    write_json_atomic(
+        cache_path(artifact), {"key": key, "sha256": sha256_file(artifact)}
+    )

netlab/autoresearch/__init__.py

@@ -0,0 +1 @@
+# LLM-assisted scenario generation and parameter searches.

netlab/autoresearch/analysis_loop.py

@@ -0,0 +1,134 @@
+"""Compute simulation metrics and request an LLM interpretation and next experiment."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .backend import LLMBackend
+from .metrics_report import build_metrics_report
+
+
+@dataclass
+class AnalysisResult:
+    """Output of the analysis loop."""
+
+    metrics_report: str
+    interpretation: str  # LLM-generated explanation
+    next_hypothesis: str  # LLM-generated suggestion for next experiment
+    iterations_used: int = 0
+    complete: bool = False
+
+    def summary(self) -> str:
+        lines = self.interpretation.strip().splitlines()
+        n_lines = len(lines)
+        preview = lines[0][:80] if lines else "(empty)"
+        return f"{n_lines} lines, {self.iterations_used} iterations: {preview}..."
+
+
+_ANALYSIS_SYSTEM_PROMPT = """\
+You are a network reliability engineer analyzing simulation results.
+
+Use the supplied metrics report to explain the topology's behavior under
+failure. Distinguish measured results from proposed explanations. Flag
+missing or inconsistent evidence, and do not invent measurements.
+
+Keep the analysis concise. Support claims about topology and failure modes
+with the scenario description and reported metrics.
+"""
+
+_ANALYSIS_PROMPT = """\
+Hypothesis being tested:
+{hypothesis}
+
+{metrics_report}
+
+Explain these results. For each failure mode:
+1. Why does BAC have this value? What structural property causes it?
+2. Does latency degrade under failure, or just bandwidth?
+3. Are both directions affected equally?
+
+Then summarize: what are the key design strengths and weaknesses of this topology?
+"""
+
+_NEXT_HYPOTHESIS_PROMPT = """\
+Based on this analysis:
+
+{interpretation}
+
+Original hypothesis:
+{hypothesis}
+
+Metrics summary:
+{metrics_summary}
+
+Propose the next topology experiment. Consider:
+- What structural variation might improve resilience?
+- What tradeoff hasn't been explored (cost vs redundancy, latency vs bandwidth)?
+- What aspect of the results is surprising or unexplained?
+
+Respond with a clear, actionable topology description that can be
+directly used to generate an ngraph scenario. Be specific about
+node counts, link capacities, and failure modes to test.
+"""
+
+
+def run_analysis_loop(
+    results: dict,
+    hypothesis: str,
+    backend: LLMBackend,
+    max_iterations: int = 3,
+) -> AnalysisResult:
+    """Build a metrics report, interpret it, and propose the next experiment.
+
+    Args:
+        results: NetGraph simulation results.
+        hypothesis: Description of the experiment being analyzed.
+        backend: LLM backend for interpretation.
+        max_iterations: Maximum attempts to obtain a nonempty interpretation.
+    """
+    if max_iterations < 1:
+        raise ValueError("max_iterations must be positive")
+    metrics_report = build_metrics_report(results)
+
+    interpretation = ""
+    attempts_used = 0
+    for _attempt in range(1, max_iterations + 1):
+        attempts_used += 1
+        prompt = _ANALYSIS_PROMPT.format(
+            hypothesis=hypothesis,
+            metrics_report=metrics_report,
+        )
+        response = backend.generate(prompt, system=_ANALYSIS_SYSTEM_PROMPT)
+        interpretation = response.strip()
+        if interpretation:
+            break
+
+    if not interpretation:
+        return AnalysisResult(
+            metrics_report=metrics_report,
+            interpretation="(LLM produced no interpretation)",
+            next_hypothesis="",
+            iterations_used=max_iterations,
+            complete=False,
+        )
+
+    # Limit the next-experiment prompt to a short metrics excerpt.
+    metrics_lines = metrics_report.splitlines()
+    metrics_summary = "\n".join(metrics_lines[:20])
+
+    next_prompt = _NEXT_HYPOTHESIS_PROMPT.format(
+        interpretation=interpretation,
+        hypothesis=hypothesis,
+        metrics_summary=metrics_summary,
+    )
+    next_hypothesis = backend.generate(
+        next_prompt, system=_ANALYSIS_SYSTEM_PROMPT
+    ).strip()
+
+    return AnalysisResult(
+        metrics_report=metrics_report,
+        interpretation=interpretation,
+        next_hypothesis=next_hypothesis,
+        iterations_used=attempts_used,
+        complete=bool(next_hypothesis),
+    )

netlab/autoresearch/backend.py

@@ -0,0 +1,270 @@
+"""LLM backends for scripted responses, CLI tools, and HTTP APIs."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from abc import ABC, abstractmethod
+from http.client import HTTPException
+from pathlib import Path
+
+from netlab.runtime import require_executable
+
+SUPPORTED_BACKENDS = ("mock", "claude-cli", "codex-cli", "openai")
+DEFAULT_CLAUDE_MODEL = "opus"
+DEFAULT_CODEX_MODEL = ""
+DEFAULT_OPENAI_MODEL = "gpt-4"
+
+
+class LLMBackend(ABC):
+    """Interface for one text-generation request."""
+
+    @abstractmethod
+    def generate(self, prompt: str, system: str = "") -> str:
+        """Return generated text; raise on failure."""
+
+
+class MockBackend(LLMBackend):
+    """Backend that returns scripted responses in order. For testing."""
+
+    def __init__(self, responses: list[str]) -> None:
+        self._responses = list(responses)
+        self._index = 0
+        self.calls: list[tuple[str, str]] = []
+
+    def generate(self, prompt: str, system: str = "") -> str:
+        self.calls.append((prompt, system))
+        if self._index >= len(self._responses):
+            raise StopIteration("MockBackend: no more scripted responses")
+        response = self._responses[self._index]
+        self._index += 1
+        return response
+
+
+class ClaudeCLIBackend(LLMBackend):
+    """Backend that calls the `claude` CLI tool via subprocess."""
+
+    def __init__(
+        self,
+        model: str = DEFAULT_CLAUDE_MODEL,
+        command: str | None = None,
+        timeout: float = 120,
+    ) -> None:
+        self.model = model
+        self.command = command
+        self.timeout = timeout
+
+    def generate(self, prompt: str, system: str = "") -> str:
+        # Claude Code headless mode uses -p/--print with the prompt as its value.
+        executable = require_executable(
+            "claude",
+            explicit=self.command,
+            env_var="CLAUDE_BIN",
+            display_name="Claude CLI",
+        )
+        cmd = [executable, "-p", prompt]
+        if self.model:
+            cmd.extend(["--model", self.model])
+        if system:
+            cmd.extend(["--system-prompt", system])
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=self.timeout,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise RuntimeError(f"Claude CLI timed out after {self.timeout}s") from exc
+        except FileNotFoundError as exc:
+            raise RuntimeError(
+                f"Claude CLI executable not found: {executable}"
+            ) from exc
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"claude CLI failed (exit {result.returncode}): {result.stderr}"
+            )
+        return result.stdout
+
+
+class CodexCLIBackend(LLMBackend):
+    """Generate text with ``codex exec`` in ephemeral, read-only mode.
+
+    Read the response from the file written by ``--output-last-message``.
+    """
+
+    def __init__(
+        self,
+        model: str = DEFAULT_CODEX_MODEL,
+        command: str | None = None,
+        timeout: float = 120,
+    ) -> None:
+        self.model = model
+        self.command = command
+        self.timeout = timeout
+
+    def generate(self, prompt: str, system: str = "") -> str:
+        full_prompt = f"{system}\n\n{prompt}" if system else prompt
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False) as tmp:
+            output_path = tmp.name
+
+        try:
+            executable = require_executable(
+                "codex",
+                explicit=self.command,
+                env_var="CODEX_BIN",
+                display_name="Codex CLI",
+            )
+            cmd = [
+                executable,
+                "exec",
+                "--ephemeral",
+                "--sandbox",
+                "read-only",
+                "--skip-git-repo-check",
+                "-o",
+                output_path,
+            ]
+            if self.model:
+                cmd.extend(["-m", self.model])
+            cmd.append(full_prompt)
+            try:
+                result = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                    timeout=self.timeout,
+                )
+            except subprocess.TimeoutExpired as exc:
+                raise RuntimeError(
+                    f"Codex CLI timed out after {self.timeout}s"
+                ) from exc
+            except FileNotFoundError as exc:
+                raise RuntimeError(
+                    f"Codex CLI executable not found: {executable}"
+                ) from exc
+            if result.returncode != 0:
+                raise RuntimeError(
+                    f"codex CLI failed (exit {result.returncode}): {result.stderr}"
+                )
+            output = Path(output_path).read_text(encoding="utf-8")
+            return output
+        finally:
+            Path(output_path).unlink(missing_ok=True)
+
+
+class OpenAICompatibleBackend(LLMBackend):
+    """Call an OpenAI-compatible HTTP API, retrying 429 and server errors."""
+
+    # Tests can override retry limits and delay.
+    max_retries: int = 3
+    base_delay: float = 2.0  # seconds
+
+    def __init__(
+        self,
+        base_url: str,
+        model: str,
+        api_key: str = "",
+        timeout: int = 120,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def generate(self, prompt: str, system: str = "") -> str:
+        # base_url may or may not include /v1 — normalize
+        base = self.base_url.rstrip("/")
+        if base.endswith("/v1"):
+            url = f"{base}/chat/completions"
+        else:
+            url = f"{base}/v1/chat/completions"
+        messages: list[dict[str, str]] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        body = json.dumps({"model": self.model, "messages": messages}).encode()
+
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        last_exc: BaseException | None = None
+        for attempt in range(self.max_retries + 1):
+            req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    data = json.loads(resp.read().decode())
+                    content = data["choices"][0]["message"]["content"]
+                    if not isinstance(content, str):
+                        raise RuntimeError("Backend response must contain text content")
+                    return content
+            except urllib.error.HTTPError as exc:
+                status = exc.code
+                if status == 429:
+                    retry_after = (
+                        exc.headers.get("Retry-After") if exc.headers else None
+                    )
+                    try:
+                        delay = (
+                            min(60.0, max(0.0, float(retry_after)))
+                            if retry_after is not None
+                            else self.base_delay * (2**attempt)
+                        )
+                    except ValueError:
+                        delay = self.base_delay * (2**attempt)
+                    last_exc = exc
+                    if attempt < self.max_retries:
+                        time.sleep(delay)
+                        continue
+                    raise RuntimeError(
+                        f"HTTP {status} after {self.max_retries + 1} attempts"
+                    ) from exc
+                elif status >= 500:
+                    delay = self.base_delay * (2**attempt)
+                    last_exc = exc
+                    if attempt < self.max_retries:
+                        time.sleep(delay)
+                        continue
+                    raise RuntimeError(
+                        f"HTTP {status} after {self.max_retries + 1} attempts"
+                    ) from exc
+                else:
+                    # 4xx (except 429): fail immediately
+                    raise RuntimeError(f"HTTP {status}: {exc.reason}") from exc
+            except urllib.error.URLError as exc:
+                # Connection refused, DNS failure, etc.
+                last_exc = exc
+                if attempt < self.max_retries:
+                    delay = self.base_delay * (2**attempt)
+                    time.sleep(delay)
+                    continue
+                raise RuntimeError(
+                    f"connection error after {self.max_retries + 1} attempts: {exc.reason}"
+                ) from exc
+            except (TimeoutError, OSError, HTTPException) as exc:
+                # Socket timeout or low-level OS error
+                last_exc = exc
+                msg = str(exc).lower()
+                if "timed out" in msg or isinstance(exc, TimeoutError):
+                    raise RuntimeError(f"timeout after {self.timeout}s: {exc}") from exc
+                # Other OS errors: retry
+                if attempt < self.max_retries:
+                    delay = self.base_delay * (2**attempt)
+                    time.sleep(delay)
+                    continue
+                raise RuntimeError(
+                    f"connection error after {self.max_retries + 1} attempts: {exc}"
+                ) from exc
+
+        raise RuntimeError(
+            f"Unexpected retry exhaustion: {last_exc}"
+        )  # pragma: no cover