@openlucaskaka/kagent 0.1.7

package/src/kagent/ops/release_manifest.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+from kagent import __version__
+
+PACKAGE_NAME = "kagent"
+
+
+def build_release_manifest(artifact_paths: Iterable[Path]) -> Dict[str, Any]:
+    artifacts = [_artifact_record(Path(path)) for path in artifact_paths]
+    return {
+        "package": PACKAGE_NAME,
+        "version": __version__,
+        "artifact_count": str(len(artifacts)),
+        "artifacts": artifacts,
+    }
+
+
+def verify_release_manifest(manifest_path: Path) -> Dict[str, Any]:
+    manifest = json.loads(Path(manifest_path).read_text(encoding="utf-8"))
+    artifacts = manifest.get("artifacts", [])
+    failures = []
+    checked = 0
+    if not isinstance(artifacts, list):
+        declared_artifact_count = str(manifest.get("artifact_count", "0"))
+        return {
+            "status": "failed",
+            "artifact_count": declared_artifact_count,
+            "checked": "0",
+            "failures": [
+                {
+                    "path": str(manifest_path),
+                    "error": "artifacts must be a list",
+                }
+            ],
+        }
+    if str(manifest.get("package", "")) != PACKAGE_NAME:
+        failures.append({"path": str(manifest_path), "error": "package mismatch"})
+    if str(manifest.get("version", "")) != __version__:
+        failures.append({"path": str(manifest_path), "error": "version mismatch"})
+    declared_artifact_count = str(manifest.get("artifact_count", len(artifacts)))
+    if declared_artifact_count != str(len(artifacts)):
+        failures.append(
+            {
+                "path": str(manifest_path),
+                "error": "artifact_count mismatch",
+            }
+        )
+    for artifact in artifacts:
+        if not isinstance(artifact, dict):
+            failures.append(
+                {
+                    "path": str(manifest_path),
+                    "error": "artifact entry must be an object",
+                }
+            )
+            continue
+        raw_path = artifact.get("path")
+        if raw_path is None or str(raw_path).strip() == "":
+            failures.append(
+                {
+                    "path": str(manifest_path),
+                    "error": "artifact path missing",
+                }
+            )
+            continue
+        path_text = str(raw_path)
+        if "\x00" in path_text:
+            failures.append(
+                {
+                    "path": str(manifest_path),
+                    "error": "artifact path invalid",
+                }
+            )
+            continue
+        path = Path(path_text)
+        checked += 1
+        if not path.exists():
+            failures.append({"path": str(path), "error": "artifact missing"})
+            continue
+        if not path.is_file():
+            failures.append({"path": str(path), "error": "artifact is not a file"})
+            continue
+        actual = _artifact_record(path)
+        if actual["sha256"] != str(artifact.get("sha256", "")):
+            failures.append({"path": str(path), "error": "sha256 mismatch"})
+            continue
+        if actual["size_bytes"] != str(artifact.get("size_bytes", "")):
+            failures.append({"path": str(path), "error": "size mismatch"})
+    return {
+        "status": "failed" if failures else "verified",
+        "artifact_count": declared_artifact_count,
+        "checked": str(checked),
+        "failures": failures,
+    }
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate a JSON release manifest with artifact sha256 hashes."
+    )
+    parser.add_argument("artifacts", nargs="*", help="Artifact file paths to include.")
+    parser.add_argument("--output", default="", metavar="PATH", help="Write manifest JSON to PATH.")
+    parser.add_argument("--verify", default="", metavar="PATH", help="Verify an existing manifest.")
+    args = parser.parse_args(argv)
+
+    try:
+        if args.verify:
+            manifest = verify_release_manifest(Path(args.verify))
+        else:
+            if not args.artifacts:
+                parser.error("at least one artifact path is required")
+            manifest = build_release_manifest([Path(path) for path in args.artifacts])
+        payload = json.dumps(manifest, indent=2, sort_keys=True) + "\n"
+        if args.output:
+            Path(args.output).write_text(payload, encoding="utf-8")
+    except json.JSONDecodeError as exc:
+        parser.error(f"invalid release manifest JSON: {exc}")
+    except OSError as exc:
+        parser.error(str(exc))
+    print(payload, end="")
+    if args.verify and manifest["status"] != "verified":
+        raise SystemExit(1)
+
+
+def _artifact_record(path: Path) -> Dict[str, str]:
+    data = path.read_bytes()
+    return {
+        "path": str(path),
+        "file_name": path.name,
+        "size_bytes": str(len(data)),
+        "sha256": hashlib.sha256(data).hexdigest(),
+    }
+
+
+if __name__ == "__main__":
+    main()

package/src/kagent/ops/trace_replay.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+from kagent.runtime.steps import derive_runtime_steps
+from kagent.utils.json_output import format_and_write_json
+
+
+def summarize_runtime_trace(trace: Dict[str, Any], *, trace_path: str = "") -> Dict[str, Any]:
+    if not isinstance(trace, dict):
+        raise ValueError("trace payload must be a JSON object")
+    observations = trace.get("observations")
+    if not isinstance(observations, list):
+        observations = []
+    events = trace.get("events")
+    if not isinstance(events, list):
+        events = []
+    progress_events = trace.get("progress_events")
+    if not isinstance(progress_events, list):
+        progress_events = []
+    steps = _steps(trace)
+    return {
+        "trace_path": trace_path,
+        "trace_type": str(trace.get("trace_type", "")),
+        "run_id": str(trace.get("run_id", "")),
+        "status": str(trace.get("status", "")),
+        "goal": str(trace.get("goal", "")),
+        "started_at": str(trace.get("started_at", "")),
+        "completed_at": str(trace.get("completed_at", "")),
+        "duration_seconds": str(trace.get("duration_seconds", "")),
+        "iterations": _iterations_label(trace),
+        "event_count": str(len(events)),
+        "progress_event_count": str(len(progress_events)),
+        "observation_count": str(len(observations)),
+        "step_count": str(len(steps)),
+        "approved_action_count": str(trace.get("approved_action_count", "0")),
+        "pending_approval": _pending_approval_summary(trace.get("pending_approval")),
+        "steps": steps,
+        "tool_counts": _count_by_key(observations, "tool"),
+        "observation_status_counts": _count_by_key(observations, "status"),
+        "failed_observations": _failed_observations(observations),
+        "changed_files": _changed_files(observations),
+        "artifacts": _artifacts(observations),
+        "progress_timeline": _progress_timeline(progress_events),
+        "timeline": _timeline(observations),
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Build a redacted replay summary for a persisted runtime trace."
+    )
+    parser.add_argument("trace_json", help="Path to a persisted runtime trace JSON file.")
+    parser.add_argument(
+        "--output",
+        default="",
+        metavar="PATH",
+        help="Write the JSON summary to PATH as well as stdout.",
+    )
+    args = parser.parse_args()
+    try:
+        trace = _read_trace(Path(args.trace_json))
+        summary = summarize_runtime_trace(trace, trace_path=args.trace_json)
+        json_payload = format_and_write_json(summary, args.output)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        parser.error(str(exc))
+    print(json_payload)
+
+
+def _read_trace(path: Path) -> Dict[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("trace payload must be a JSON object")
+    return payload
+
+
+def _iterations_label(trace: Dict[str, Any]) -> str:
+    iteration_count = str(trace.get("iteration_count", "")).strip()
+    max_iterations = str(trace.get("max_iterations", "")).strip()
+    if iteration_count and max_iterations:
+        return f"{iteration_count}/{max_iterations}"
+    return iteration_count
+
+
+def _pending_approval_summary(value: Any) -> Dict[str, str]:
+    if not isinstance(value, dict):
+        return {}
+    return {
+        "id": str(value.get("id", "")),
+        "tool": str(value.get("tool", "")),
+        "reason": str(value.get("reason", "")),
+    }
+
+
+def _steps(trace: Dict[str, Any]) -> List[Dict[str, str]]:
+    raw_steps = trace.get("steps")
+    if isinstance(raw_steps, list):
+        steps = _sanitize_steps(raw_steps)
+        if steps:
+            return steps
+    return _sanitize_steps(derive_runtime_steps(_trace_with_latest_plan(trace)))
+
+
+def _trace_with_latest_plan(trace: Dict[str, Any]) -> Dict[str, Any]:
+    if isinstance(trace.get("plan"), dict):
+        return trace
+    plans = trace.get("plans")
+    if not isinstance(plans, list):
+        return trace
+    for item in reversed(plans):
+        if isinstance(item, dict):
+            return {**trace, "plan": item}
+    return trace
+
+
+def _sanitize_steps(value: Any) -> List[Dict[str, str]]:
+    if not isinstance(value, list):
+        return []
+    steps = []
+    for item in value:
+        if not isinstance(item, dict):
+            continue
+        index = _scalar(item.get("index"))
+        state = _scalar(item.get("state"))
+        title = _scalar(item.get("title"))
+        if state not in {"done", "failed", "pending", "waiting_approval"}:
+            continue
+        if not index or not title:
+            continue
+        step = {
+            "index": index,
+            "state": state,
+            "title": title,
+        }
+        detail = _scalar(item.get("detail"))
+        if detail:
+            step["detail"] = detail
+        steps.append(step)
+    return steps
+
+
+def _scalar(value: Any) -> str:
+    if isinstance(value, bool):
+        return ""
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return str(value)
+    return ""
+
+
+def _count_by_key(observations: List[Any], key: str) -> Dict[str, str]:
+    counts: Dict[str, int] = {}
+    for observation in observations:
+        if not isinstance(observation, dict):
+            continue
+        value = str(observation.get(key, "")).strip()
+        if not value:
+            continue
+        counts[value] = counts.get(value, 0) + 1
+    return {key: str(counts[key]) for key in sorted(counts)}
+
+
+def _failed_observations(observations: List[Any]) -> List[Dict[str, str]]:
+    failed = []
+    for observation in observations:
+        if not isinstance(observation, dict):
+            continue
+        if str(observation.get("status", "")) not in {"failed", "requires_approval"}:
+            continue
+        failed.append(
+            {
+                "action_id": str(observation.get("action_id", "")),
+                "tool": str(observation.get("tool", "")),
+                "status": str(observation.get("status", "")),
+                "error_code": str(observation.get("error_code", "")),
+                "error": str(observation.get("error", "")),
+            }
+        )
+    return failed
+
+
+def _changed_files(observations: List[Any]) -> List[Dict[str, str]]:
+    changed = []
+    for observation in observations:
+        if not isinstance(observation, dict):
+            continue
+        output = observation.get("output")
+        if not isinstance(output, dict):
+            continue
+        files = output.get("changed_files")
+        if not isinstance(files, list):
+            continue
+        for item in files:
+            if not isinstance(item, dict):
+                continue
+            changed.append(
+                {
+                    "action_id": str(observation.get("action_id", "")),
+                    "path": str(item.get("path", "")),
+                    "previous_path": str(item.get("previous_path", "")),
+                    "operation": str(item.get("operation", "")),
+                    "bytes": str(item.get("bytes", "")),
+                    "sha256": str(item.get("sha256", "")),
+                }
+            )
+    return changed
+
+
+def _artifacts(observations: List[Any]) -> List[Dict[str, str]]:
+    artifacts = []
+    for observation in observations:
+        if not isinstance(observation, dict):
+            continue
+        output = observation.get("output")
+        if not isinstance(output, dict):
+            continue
+        artifact_id = str(output.get("artifact_id", "")).strip()
+        if not artifact_id:
+            continue
+        artifacts.append(
+            {
+                "action_id": str(observation.get("action_id", "")),
+                "artifact_id": artifact_id,
+                "title": str(output.get("title", "")),
+                "kind": str(output.get("kind", "")),
+                "format": str(output.get("format", "")),
+                "bytes": str(output.get("bytes", "")),
+            }
+        )
+    return artifacts
+
+
+def _timeline(observations: List[Any]) -> List[Dict[str, str]]:
+    timeline = []
+    for observation in observations:
+        if not isinstance(observation, dict):
+            continue
+        timeline.append(
+            {
+                "action_id": str(observation.get("action_id", "")),
+                "tool": str(observation.get("tool", "")),
+                "status": str(observation.get("status", "")),
+                "error_code": str(observation.get("error_code", "")),
+                "duration_seconds": str(observation.get("duration_seconds", "")),
+            }
+        )
+    return timeline
+
+
+def _progress_timeline(progress_events: List[Any]) -> List[Dict[str, str]]:
+    timeline = []
+    fields = [
+        "type",
+        "node",
+        "status",
+        "iteration",
+        "action_id",
+        "tool",
+        "reason",
+        "error_code",
+        "action_count",
+        "iteration_count",
+        "duration_seconds",
+    ]
+    for item in progress_events:
+        if not isinstance(item, dict):
+            continue
+        event = {
+            field: str(item[field])
+            for field in fields
+            if field in item and str(item[field]).strip()
+        }
+        if event:
+            timeline.append(event)
+    return timeline
+
+
+if __name__ == "__main__":
+    main()

package/src/kagent/providers/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from kagent.providers import llm
+
+llm_provider = llm
+
+__all__ = ["llm", "llm_provider"]

package/src/kagent/providers/embeddings.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from os import environ
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+
+@dataclass(frozen=True)
+class EmbeddingProviderConfig:
+    base_url: str = ""
+    api_key: str = ""
+    model: str = ""
+    timeout_seconds: float = 30.0
+    max_retries: int = 2
+    retry_backoff_seconds: float = 0.25
+
+    @classmethod
+    def from_env(
+        cls,
+        env: Optional[Mapping[str, str]] = None,
+    ) -> "EmbeddingProviderConfig":
+        source = env if env is not None else environ
+        return cls(
+            base_url=source.get(
+                "KAGENT_EMBEDDING_BASE_URL",
+                source.get("KAGENT_LLM_BASE_URL", cls.base_url),
+            ),
+            api_key=source.get(
+                "KAGENT_EMBEDDING_API_KEY",
+                source.get("KAGENT_LLM_API_KEY", cls.api_key),
+            ),
+            model=source.get("KAGENT_EMBEDDING_MODEL", cls.model),
+            timeout_seconds=_env_float(
+                source,
+                "KAGENT_EMBEDDING_TIMEOUT_SECONDS",
+                cls.timeout_seconds,
+            ),
+            max_retries=_env_int(
+                source,
+                "KAGENT_EMBEDDING_MAX_RETRIES",
+                cls.max_retries,
+            ),
+            retry_backoff_seconds=_env_float(
+                source,
+                "KAGENT_EMBEDDING_RETRY_BACKOFF_SECONDS",
+                cls.retry_backoff_seconds,
+            ),
+        )
+
+    def redacted_snapshot(self) -> Dict[str, str]:
+        provider = "openai_compatible" if self.base_url and self.model else "unconfigured"
+        base_url_configured = bool(self.base_url)
+        return {
+            "embedding_provider": provider,
+            "embedding_base_url": "configured" if base_url_configured else "",
+            "embedding_base_url_configured": str(base_url_configured).lower(),
+            "embedding_model": self.model,
+            "embedding_api_key_configured": str(bool(self.api_key)).lower(),
+            "embedding_timeout_seconds": str(self.timeout_seconds),
+            "embedding_max_retries": str(self.max_retries),
+            "embedding_retry_backoff_seconds": str(self.retry_backoff_seconds),
+        }
+
+    def __post_init__(self) -> None:
+        if self.timeout_seconds <= 0:
+            raise ValueError("embedding timeout_seconds must be positive")
+        if self.max_retries < 0:
+            raise ValueError("embedding max_retries must be non-negative")
+        if self.retry_backoff_seconds < 0:
+            raise ValueError("embedding retry_backoff_seconds must be non-negative")
+
+
+class OpenAICompatibleEmbeddingProvider:
+    def __init__(
+        self,
+        config: EmbeddingProviderConfig,
+        *,
+        urlopen: Callable[..., Any] = urllib.request.urlopen,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        if not config.base_url:
+            raise ValueError("embedding base_url is required")
+        if not config.model:
+            raise ValueError("embedding model is required")
+        self.config = config
+        self._urlopen = urlopen
+        self._sleep = sleep
+
+    def embed(self, text: str) -> List[float]:
+        normalized_text = str(text).strip()
+        if not normalized_text:
+            raise ValueError("embedding text is required")
+        request = self._embedding_request(normalized_text)
+        body = self._request_json_with_retries(request)
+        try:
+            vector = body["data"][0]["embedding"]
+        except (KeyError, IndexError, TypeError) as exc:
+            raise RuntimeError("embedding provider response missing vector") from exc
+        if not isinstance(vector, list) or not vector:
+            raise RuntimeError("embedding provider response missing vector")
+        normalized_vector = []
+        for item in vector:
+            if isinstance(item, bool) or not isinstance(item, (int, float)):
+                raise RuntimeError("embedding provider vector must contain numbers")
+            normalized_vector.append(float(item))
+        return normalized_vector
+
+    def _embedding_request(self, text: str) -> urllib.request.Request:
+        endpoint = self.config.base_url.rstrip("/") + "/embeddings"
+        payload = {
+            "input": text,
+            "model": self.config.model,
+        }
+        headers = {"Content-Type": "application/json"}
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+        return urllib.request.Request(
+            endpoint,
+            data=json.dumps(payload).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+
+    def _request_json_with_retries(
+        self,
+        request: urllib.request.Request,
+    ) -> Dict[str, Any]:
+        max_attempts = self.config.max_retries + 1
+        for attempt in range(max_attempts):
+            try:
+                with self._urlopen(
+                    request,
+                    timeout=self.config.timeout_seconds,
+                ) as response:
+                    body = json.loads(response.read().decode("utf-8"))
+                    if int(response.status) < 200 or int(response.status) >= 300:
+                        raise RuntimeError("embedding provider request failed")
+                    if not isinstance(body, dict):
+                        raise RuntimeError("embedding provider response must be an object")
+                    return body
+            except urllib.error.HTTPError as exc:
+                if attempt >= max_attempts - 1 or not _is_retryable_embedding_error(
+                    exc
+                ):
+                    raise RuntimeError(
+                        f"embedding provider request failed: http_status={exc.code}"
+                    ) from exc
+                if self.config.retry_backoff_seconds:
+                    self._sleep(self.config.retry_backoff_seconds)
+            except (urllib.error.URLError, TimeoutError) as exc:
+                if attempt >= max_attempts - 1:
+                    raise RuntimeError(
+                        "embedding provider request failed: network_error"
+                    ) from exc
+                if self.config.retry_backoff_seconds:
+                    self._sleep(self.config.retry_backoff_seconds)
+        raise RuntimeError("embedding provider request failed")
+
+
+def _env_float(env: Mapping[str, str], name: str, default: float) -> float:
+    value = env.get(name)
+    if value in {None, ""}:
+        return default
+    try:
+        return float(value)
+    except ValueError as exc:
+        raise ValueError(f"{name} must be a number") from exc
+
+
+def _env_int(env: Mapping[str, str], name: str, default: int) -> int:
+    value = env.get(name)
+    if value in {None, ""}:
+        return default
+    try:
+        return int(value)
+    except ValueError as exc:
+        raise ValueError(f"{name} must be an integer") from exc
+
+
+def _is_retryable_embedding_error(exc: BaseException) -> bool:
+    if isinstance(exc, urllib.error.HTTPError):
+        return exc.code == 429 or 500 <= exc.code <= 599
+    return isinstance(exc, (urllib.error.URLError, TimeoutError))