harbor-dsh-evolution 0.1.0__tar.gz

harbor_dsh_evolution-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+dist/
+
+# Harbor execution results are local evidence, not template source.
+jobs/*
+!jobs/.gitkeep
+
+# Local Docker/Buildx state.
+.runtime/
+
+# Generated Candidate snapshots and local package installs.
+examples/**/candidate-manifest.json
+examples/**/node_modules/
+packages/**/node_modules/

harbor_dsh_evolution-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 istarwyh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

harbor_dsh_evolution-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: harbor-dsh-evolution
+Version: 0.1.0
+Summary: Candidate identity, evaluation summaries, and promotion gates for DeepSeek Harness agents evaluated with Harbor.
+Project-URL: Homepage, https://github.com/istarwyh/harbor-self-evolving
+Project-URL: Documentation, https://github.com/istarwyh/harbor-self-evolving#readme
+Project-URL: Issues, https://github.com/istarwyh/harbor-self-evolving/issues
+Project-URL: Repository, https://github.com/istarwyh/harbor-self-evolving.git
+Author: istarwyh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-evaluation,agent-evolution,deepseek-harness,harbor
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: harbor<0.22,>=0.21.0
+Description-Content-Type: text/markdown
+
+# harbor-dsh-evolution
+
+Harbor-side integration for DeepSeek Harness Candidate evolution.
+
+It provides:
+
+- `DshCandidateAgent`: verifies and uploads an immutable Candidate, installs its locked npm dependencies, and runs it through Harbor's ACP runner.
+- `EvolutionPlugin`: records Candidate identity, evaluation-context identity, Trial events, and `evaluation-summary.json` for each Job.
+- `harbor-dsh`: snapshots/verifies Candidates, fingerprints datasets, summarizes Jobs, and runs the deterministic Promotion Gate.
+
+Install it into the same Python environment as Harbor so the plugin entry point is discoverable:
+
+```bash
+uv venv .venv
+uv pip install --python .venv/bin/python harbor-dsh-evolution
+source .venv/bin/activate
+harbor plugins list
+harbor-dsh --help
+```
+
+Development from this repository:
+
+```bash
+uv sync
+uv run harbor plugins list
+uv run harbor-dsh --help
+uv run harbor-dsh context ../../examples/deep-research/task
+uv run pytest
+uv build
+```
+
+Harbor and this package must be installed into the same Python environment for the `dsh-evolution` entry point to appear in `harbor plugins list`.
+
+`snapshot` derives Candidate id and version from `package.json` unless they are explicitly supplied. Promotion rejects Jobs whose `evaluation-context` digests are missing or different.

harbor_dsh_evolution-0.1.0/README.md

@@ -0,0 +1,34 @@
+# harbor-dsh-evolution
+
+Harbor-side integration for DeepSeek Harness Candidate evolution.
+
+It provides:
+
+- `DshCandidateAgent`: verifies and uploads an immutable Candidate, installs its locked npm dependencies, and runs it through Harbor's ACP runner.
+- `EvolutionPlugin`: records Candidate identity, evaluation-context identity, Trial events, and `evaluation-summary.json` for each Job.
+- `harbor-dsh`: snapshots/verifies Candidates, fingerprints datasets, summarizes Jobs, and runs the deterministic Promotion Gate.
+
+Install it into the same Python environment as Harbor so the plugin entry point is discoverable:
+
+```bash
+uv venv .venv
+uv pip install --python .venv/bin/python harbor-dsh-evolution
+source .venv/bin/activate
+harbor plugins list
+harbor-dsh --help
+```
+
+Development from this repository:
+
+```bash
+uv sync
+uv run harbor plugins list
+uv run harbor-dsh --help
+uv run harbor-dsh context ../../examples/deep-research/task
+uv run pytest
+uv build
+```
+
+Harbor and this package must be installed into the same Python environment for the `dsh-evolution` entry point to appear in `harbor plugins list`.
+
+`snapshot` derives Candidate id and version from `package.json` unless they are explicitly supplied. Promotion rejects Jobs whose `evaluation-context` digests are missing or different.

harbor_dsh_evolution-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "harbor-dsh-evolution"
+version = "0.1.0"
+description = "Candidate identity, evaluation summaries, and promotion gates for DeepSeek Harness agents evaluated with Harbor."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "istarwyh" }]
+keywords = [
+  "agent-evaluation",
+  "agent-evolution",
+  "deepseek-harness",
+  "harbor",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = ["harbor>=0.21.0,<0.22"]
+
+[project.urls]
+Homepage = "https://github.com/istarwyh/harbor-self-evolving"
+Documentation = "https://github.com/istarwyh/harbor-self-evolving#readme"
+Issues = "https://github.com/istarwyh/harbor-self-evolving/issues"
+Repository = "https://github.com/istarwyh/harbor-self-evolving.git"
+
+[project.entry-points."harbor.plugins"]
+dsh-evolution = "harbor_dsh_evolution.plugin:EvolutionPlugin"
+
+[project.scripts]
+harbor-dsh = "harbor_dsh_evolution.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8.4", "pytest-asyncio>=1.0"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/harbor_dsh_evolution"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

harbor_dsh_evolution-0.1.0/src/harbor_dsh_evolution/__init__.py

@@ -0,0 +1,7 @@
+"""Harbor integration for DeepSeek Harness Candidate evolution.
+
+Keep this module dependency-free so the Candidate CLI can create and verify
+manifests even when it is invoked outside Harbor's Python environment.
+"""
+
+__version__ = "0.1.0"

harbor_dsh_evolution-0.1.0/src/harbor_dsh_evolution/agent.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+import shlex
+from pathlib import Path
+from typing import override
+
+from harbor.agents.installed.acp import AcpAgent, DistributionKind
+from harbor.environments.base import BaseEnvironment
+from harbor.models.agent.context import AgentContext
+
+from harbor_dsh_evolution.candidate import CandidateManifest, verify_candidate
+
+
+class DshCandidateAgent(AcpAgent):
+    """Run one immutable DeepSeek Harness Candidate through Harbor's ACP runner."""
+
+    _REMOTE_ROOT = "/opt/harbor-dsh-candidate"
+    _DSH_ACP_PACKAGE = "@deepseek-ai/dsh-acp-demo@0.1.0-rc.6"
+
+    def __init__(
+        self,
+        logs_dir: Path,
+        candidate_path: str,
+        candidate_digest: str,
+        candidate_version: str | None = None,
+        **kwargs,
+    ) -> None:
+        self.candidate_path = Path(candidate_path).expanduser().resolve(strict=True)
+        self.manifest: CandidateManifest = verify_candidate(
+            self.candidate_path, expected_digest=candidate_digest
+        )
+        if candidate_version is not None and candidate_version != self.manifest.version:
+            raise ValueError(
+                "Candidate version mismatch: "
+                f"requested={candidate_version}, manifest={self.manifest.version}"
+            )
+        self.candidate_digest = candidate_digest
+
+        registry_entry = {
+            "id": self.manifest.candidate_id,
+            "name": f"DeepSeek Harness Candidate {self.manifest.candidate_id}",
+            "version": self.manifest.version,
+            "description": "Immutable Cordis composition evaluated through ACP.",
+            "distribution": {
+                "npx": {
+                    "package": self._DSH_ACP_PACKAGE,
+                    "args": ["--config", f"{self._REMOTE_ROOT}/cordis.yml"],
+                    "env": {
+                        "DSH_SESSION_ROOT": f"{self._REMOTE_ROOT}/.sessions",
+                    },
+                }
+            },
+        }
+        super().__init__(
+            logs_dir=logs_dir,
+            registry_entry=registry_entry,
+            distribution_preference="npx",
+            auth_policy="disabled",
+            # This adapter only exposes an architecture-neutral npx distribution.
+            # Supplying a supported platform avoids a best-effort uname probe on
+            # deliberately minimal task images where that probe can be unavailable.
+            target_platform="linux-x86_64",
+            **kwargs,
+        )
+
+    @staticmethod
+    @override
+    def name() -> str:
+        return "dsh-candidate"
+
+    @override
+    def version(self) -> str:
+        return self.manifest.version
+
+    @override
+    def _build_dependencies_command(self, kind: DistributionKind) -> str:
+        """Avoid network installation when the Task image is ACP-ready.
+
+        Harbor's generic ACP installer supports arbitrary base images, but a
+        stable evaluation image should pin these dependencies at build time.
+        ``stdbuf`` is included because Harbor's ACP log pipeline requires it.
+        """
+        install = super()._build_dependencies_command(kind)
+        return f"""
+set -euo pipefail
+if command -v bash >/dev/null 2>&1 \
+  && command -v python3 >/dev/null 2>&1 \
+  && command -v curl >/dev/null 2>&1 \
+  && command -v node >/dev/null 2>&1 \
+  && command -v npm >/dev/null 2>&1 \
+  && command -v stdbuf >/dev/null 2>&1 \
+  && [ -x {self._RUNNER_VENV_PATH}/bin/python ] \
+  && {self._RUNNER_VENV_PATH}/bin/python -c 'import acp' >/dev/null 2>&1; then
+  exit 0
+fi
+{install}
+if ! command -v stdbuf >/dev/null 2>&1; then
+  if command -v apk >/dev/null 2>&1; then
+    apk add --no-cache coreutils
+  elif command -v apt-get >/dev/null 2>&1; then
+    apt-get install -y coreutils
+  fi
+fi
+""".strip()
+
+    @override
+    async def setup(self, environment: BaseEnvironment) -> None:
+        await super().setup(environment)
+        await environment.exec(
+            f"rm -rf {shlex.quote(self._REMOTE_ROOT)} && "
+            f"mkdir -p {shlex.quote(self._REMOTE_ROOT)}",
+            user="root",
+        )
+        await environment.upload_dir(self.candidate_path, self._REMOTE_ROOT)
+
+        package_command = (
+            "npm ci" if (self.candidate_path / "package-lock.json").is_file()
+            else "npm install"
+        )
+        install = await environment.exec(
+            f"{package_command} --omit=dev --ignore-scripts --no-audit --no-fund",
+            cwd=self._REMOTE_ROOT,
+            user="root",
+            timeout_sec=600,
+        )
+        if install.return_code != 0:
+            raise RuntimeError(
+                "Failed to install Candidate runtime dependencies: "
+                f"{install.stderr or install.stdout}"
+            )
+        await environment.exec(
+            f"chmod -R a+rX {shlex.quote(self._REMOTE_ROOT)}", user="root"
+        )
+
+    @override
+    def populate_context_post_run(self, context: AgentContext) -> None:
+        super().populate_context_post_run(context)
+        metadata = dict(context.metadata or {})
+        metadata["candidate"] = {
+            "id": self.manifest.candidate_id,
+            "version": self.manifest.version,
+            "digest": self.candidate_digest,
+            "runtime": self.manifest.runtime,
+        }
+        context.metadata = metadata
+
+        self.logs_dir.mkdir(parents=True, exist_ok=True)
+        (self.logs_dir / "candidate.json").write_text(
+            json.dumps(metadata["candidate"], ensure_ascii=False, indent=2) + "\n"
+        )

harbor_dsh_evolution-0.1.0/src/harbor_dsh_evolution/candidate.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+MANIFEST_NAME = "candidate-manifest.json"
+_DIGEST_PREFIX = b"harbor-dsh-candidate-v1\0"
+_EXCLUDED_DIRS = {".git", "node_modules", "__pycache__"}
+_EXCLUDED_FILES = {MANIFEST_NAME, ".DS_Store"}
+_DIGEST_PATTERN = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+@dataclass(frozen=True)
+class CandidateFile:
+    path: str
+    size: int
+    sha256: str
+
+
+@dataclass(frozen=True)
+class CandidateManifest:
+    schema_version: int
+    candidate_id: str
+    version: str
+    digest: str
+    created_at: str
+    runtime: dict[str, str]
+    files: list[CandidateFile]
+    metadata: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "CandidateManifest":
+        schema_version = int(value["schema_version"])
+        if schema_version != 1:
+            raise ValueError(f"Unsupported Candidate schema_version: {schema_version}")
+        candidate_id = str(value["candidate_id"])
+        version = str(value["version"])
+        digest = str(value["digest"])
+        if not candidate_id or not version:
+            raise ValueError("Candidate id and version must not be empty")
+        if not _DIGEST_PATTERN.fullmatch(digest):
+            raise ValueError(f"Invalid Candidate digest: {digest}")
+        return cls(
+            schema_version=schema_version,
+            candidate_id=candidate_id,
+            version=version,
+            digest=digest,
+            created_at=str(value["created_at"]),
+            runtime=dict(value["runtime"]),
+            files=[CandidateFile(**item) for item in value["files"]],
+            metadata=dict(value.get("metadata") or {}),
+        )
+
+
+def _candidate_files(candidate_dir: Path) -> list[Path]:
+    paths: list[Path] = []
+    for path in candidate_dir.rglob("*"):
+        relative = path.relative_to(candidate_dir)
+        if any(part in _EXCLUDED_DIRS for part in relative.parts):
+            continue
+        if path.name in _EXCLUDED_FILES:
+            continue
+        if path.is_symlink():
+            raise ValueError(f"Candidate must not contain symlinks: {relative}")
+        if path.is_file():
+            paths.append(path)
+    return sorted(paths, key=lambda item: item.relative_to(candidate_dir).as_posix())
+
+
+def compute_candidate(candidate_dir: Path) -> tuple[str, list[CandidateFile]]:
+    candidate_dir = candidate_dir.expanduser().resolve(strict=True)
+    if not candidate_dir.is_dir():
+        raise ValueError(f"Candidate path is not a directory: {candidate_dir}")
+
+    digest = hashlib.sha256()
+    digest.update(_DIGEST_PREFIX)
+    files: list[CandidateFile] = []
+    for path in _candidate_files(candidate_dir):
+        relative = path.relative_to(candidate_dir).as_posix()
+        content = path.read_bytes()
+        file_digest = hashlib.sha256(content).hexdigest()
+        files.append(
+            CandidateFile(path=relative, size=len(content), sha256=file_digest)
+        )
+        digest.update(relative.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(str(len(content)).encode("ascii"))
+        digest.update(b"\0")
+        digest.update(content)
+        digest.update(b"\0")
+    return f"sha256:{digest.hexdigest()}", files
+
+
+def snapshot_candidate(
+    candidate_dir: Path,
+    *,
+    candidate_id: str | None = None,
+    version: str | None = None,
+    runtime_version: str = "0.1.0-rc.6",
+    metadata: dict[str, Any] | None = None,
+) -> CandidateManifest:
+    candidate_dir = candidate_dir.expanduser().resolve(strict=True)
+    required = [candidate_dir / "cordis.yml", candidate_dir / "package.json"]
+    missing = [path.name for path in required if not path.is_file()]
+    if missing:
+        raise ValueError(f"Candidate is missing required files: {', '.join(missing)}")
+
+    try:
+        package = json.loads((candidate_dir / "package.json").read_text())
+    except json.JSONDecodeError as error:
+        raise ValueError("Candidate package.json is not valid JSON") from error
+    if candidate_id is None:
+        candidate_id = str(package.get("name") or "")
+    if version is None:
+        version = str(package.get("version") or "")
+    if not candidate_id or not version or not runtime_version:
+        raise ValueError(
+            "Candidate id, version, and runtime version must not be empty; "
+            "set package.json name/version or pass explicit values"
+        )
+
+    digest, files = compute_candidate(candidate_dir)
+    manifest = CandidateManifest(
+        schema_version=1,
+        candidate_id=candidate_id,
+        version=version,
+        digest=digest,
+        created_at=datetime.now(timezone.utc).isoformat(),
+        runtime={
+            "kind": "deepseek-harness",
+            "version": runtime_version,
+            "transport": "acp",
+        },
+        files=files,
+        metadata=metadata or {},
+    )
+    (candidate_dir / MANIFEST_NAME).write_text(
+        json.dumps(manifest.to_dict(), ensure_ascii=False, indent=2) + "\n"
+    )
+    return manifest
+
+
+def load_manifest(candidate_dir: Path) -> CandidateManifest:
+    path = candidate_dir.expanduser().resolve(strict=True) / MANIFEST_NAME
+    return CandidateManifest.from_dict(json.loads(path.read_text()))
+
+
+def verify_candidate(
+    candidate_dir: Path,
+    *,
+    expected_digest: str | None = None,
+) -> CandidateManifest:
+    candidate_dir = candidate_dir.expanduser().resolve(strict=True)
+    manifest = load_manifest(candidate_dir)
+    actual_digest, actual_files = compute_candidate(candidate_dir)
+    if actual_digest != manifest.digest:
+        raise ValueError(
+            "Candidate digest mismatch: "
+            f"manifest={manifest.digest}, actual={actual_digest}"
+        )
+    if expected_digest is not None and actual_digest != expected_digest:
+        raise ValueError(
+            "Candidate does not match requested digest: "
+            f"expected={expected_digest}, actual={actual_digest}"
+        )
+    if actual_files != manifest.files:
+        raise ValueError("Candidate file inventory does not match its manifest")
+    return manifest

harbor_dsh_evolution-0.1.0/src/harbor_dsh_evolution/cli.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from harbor_dsh_evolution.candidate import snapshot_candidate, verify_candidate
+from harbor_dsh_evolution.context import build_evaluation_context
+from harbor_dsh_evolution.promotion import compare_jobs, write_report
+from harbor_dsh_evolution.summary import load_or_create_summary
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="harbor-dsh")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    snapshot = commands.add_parser("snapshot", help="Freeze a Candidate directory")
+    snapshot.add_argument("candidate_dir", type=Path)
+    snapshot.add_argument("--id", dest="candidate_id")
+    snapshot.add_argument("--version")
+    snapshot.add_argument("--runtime-version", default="0.1.0-rc.6")
+
+    verify = commands.add_parser("verify", help="Verify a Candidate digest")
+    verify.add_argument("candidate_dir", type=Path)
+    verify.add_argument("--digest")
+
+    summary = commands.add_parser("summarize", help="Summarize a Harbor Job")
+    summary.add_argument("job_dir", type=Path)
+
+    context = commands.add_parser("context", help="Fingerprint a Harbor dataset")
+    context.add_argument("dataset_dir", type=Path)
+
+    promote = commands.add_parser("promote", help="Apply a Promotion Gate")
+    promote.add_argument("baseline_job", type=Path)
+    promote.add_argument("candidate_job", type=Path)
+    promote.add_argument("--policy", required=True, type=Path)
+    promote.add_argument("--output", type=Path)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    if args.command == "snapshot":
+        result = snapshot_candidate(
+            args.candidate_dir,
+            candidate_id=args.candidate_id,
+            version=args.version,
+            runtime_version=args.runtime_version,
+        ).to_dict()
+    elif args.command == "verify":
+        result = verify_candidate(
+            args.candidate_dir, expected_digest=args.digest
+        ).to_dict()
+    elif args.command == "summarize":
+        result = load_or_create_summary(args.job_dir)
+    elif args.command == "context":
+        result = build_evaluation_context(args.dataset_dir).to_dict()
+    else:
+        report = compare_jobs(args.baseline_job, args.candidate_job, args.policy)
+        output = args.output or args.candidate_job / "promotion-report.json"
+        write_report(report, output)
+        result = report
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result.get("decision") != "REJECT" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())