agenthealth 0.13.2__tar.gz

agenthealth-0.13.2/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

agenthealth-0.13.2/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: agenthealth
+Version: 0.13.2
+Summary: Typed synchronous and asynchronous Python access to the AgentHealth CLI
+Author: TheAgentHealth
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/TheAgentHealth/agenthealth
+Project-URL: Documentation, https://github.com/TheAgentHealth/agenthealth/blob/main/docs/python-sdk.md
+Project-URL: Issues, https://github.com/TheAgentHealth/agenthealth/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema<5,>=4.18
+Requires-Dist: PyYAML<7,>=6
+Dynamic: license-file
+
+# AgentHealth Python SDK
+
+Typed synchronous and asynchronous access to AgentHealth's Go CLI. This package
+preserves AHS v1 results, diagnostic codes, dependency relationships and graph
+IDs. Health failures return results; tool failures raise exceptions.
+
+Install the package with `pip install agenthealth` once published. Install a
+verified AgentHealth CLI of the same software version separately and put it on
+PATH, or pass its absolute path. Installation and imports never download or
+execute a binary. This first SDK targets Python 3.10+ and CLI v0.13.2.
+
+```python
+from agenthealth import Client, HealthStatus
+
+client = Client(binary="/usr/local/bin/agenthealth", timeout=30)
+report = client.check(target_type="http", endpoint="http://localhost:8080/health")
+print(report.status, report.exit_code)
+if report.status == HealthStatus.HEALTHY:
+    print(report.result.target.name)
+```
+
+```python
+from agenthealth import async_check
+
+async def probe():
+    return await async_check("agenthealth.yaml")
+```
+
+Use `Configuration` for Python dictionaries or `load_config` for JSON/YAML.
+The same configuration supports all implemented CLI adapters, explicit active
+checks, nested dependencies and graph references. Credentials stay in configured
+references. Configuration is trusted executable input: MCP stdio can launch
+programs and endpoints can reach private networks. Loading validates schema;
+Go validates graph semantics at execution.
+
+The SDK checks the exact CLI version, bounds configuration and output, enforces
+an overall deadline and stops checks on timeout/cancellation. POSIX checks use
+a dedicated process group to clean up descendants. On Windows termination
+covers the CLI process; detached stdio descendants require operator lifecycle
+controls. CLI stderr is never included in exceptions.
+
+The SDK does not aggregate health independently, run OAuth login, register
+Python adapters, or auto-install the CLI. `report.results` preserves ordered
+roots, including each dependency projection. `to_dict()` preserves additional
+result fields. Relative paths retain the caller's working directory, matching
+the CLI; `Configuration(data, base_dir=...)` selects a different directory.
+
+Source implementation is pre-1.0; PyPI availability is recorded separately in
+the repository capability status. See the repository's Python SDK guide for
+installation, release setup, errors and examples.

agenthealth-0.13.2/README.md

@@ -0,0 +1,50 @@
+# AgentHealth Python SDK
+
+Typed synchronous and asynchronous access to AgentHealth's Go CLI. This package
+preserves AHS v1 results, diagnostic codes, dependency relationships and graph
+IDs. Health failures return results; tool failures raise exceptions.
+
+Install the package with `pip install agenthealth` once published. Install a
+verified AgentHealth CLI of the same software version separately and put it on
+PATH, or pass its absolute path. Installation and imports never download or
+execute a binary. This first SDK targets Python 3.10+ and CLI v0.13.2.
+
+```python
+from agenthealth import Client, HealthStatus
+
+client = Client(binary="/usr/local/bin/agenthealth", timeout=30)
+report = client.check(target_type="http", endpoint="http://localhost:8080/health")
+print(report.status, report.exit_code)
+if report.status == HealthStatus.HEALTHY:
+    print(report.result.target.name)
+```
+
+```python
+from agenthealth import async_check
+
+async def probe():
+    return await async_check("agenthealth.yaml")
+```
+
+Use `Configuration` for Python dictionaries or `load_config` for JSON/YAML.
+The same configuration supports all implemented CLI adapters, explicit active
+checks, nested dependencies and graph references. Credentials stay in configured
+references. Configuration is trusted executable input: MCP stdio can launch
+programs and endpoints can reach private networks. Loading validates schema;
+Go validates graph semantics at execution.
+
+The SDK checks the exact CLI version, bounds configuration and output, enforces
+an overall deadline and stops checks on timeout/cancellation. POSIX checks use
+a dedicated process group to clean up descendants. On Windows termination
+covers the CLI process; detached stdio descendants require operator lifecycle
+controls. CLI stderr is never included in exceptions.
+
+The SDK does not aggregate health independently, run OAuth login, register
+Python adapters, or auto-install the CLI. `report.results` preserves ordered
+roots, including each dependency projection. `to_dict()` preserves additional
+result fields. Relative paths retain the caller's working directory, matching
+the CLI; `Configuration(data, base_dir=...)` selects a different directory.
+
+Source implementation is pre-1.0; PyPI availability is recorded separately in
+the repository capability status. See the repository's Python SDK guide for
+installation, release setup, errors and examples.

agenthealth-0.13.2/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools==80.9.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agenthealth"
+version = "0.13.2"
+description = "Typed synchronous and asynchronous Python access to the AgentHealth CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{name = "TheAgentHealth"}]
+dependencies = ["jsonschema>=4.18,<5", "PyYAML>=6,<7"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/TheAgentHealth/agenthealth"
+Documentation = "https://github.com/TheAgentHealth/agenthealth/blob/main/docs/python-sdk.md"
+Issues = "https://github.com/TheAgentHealth/agenthealth/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+agenthealth = ["py.typed", "schemas/*.json"]

agenthealth-0.13.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agenthealth-0.13.2/src/agenthealth/__init__.py

@@ -0,0 +1,12 @@
+"""AgentHealth Python SDK. Installation does not install the CLI."""
+from .client import Client, async_check, check
+from .config import Configuration, load_config
+from .errors import (AgentHealthError, BinaryNotFoundError, CheckTimeoutError,
+                     CompatibilityError, ConfigurationError, ExecutionError, OutputError)
+from .models import CheckEntry, CheckReport, HealthResult, HealthStatus, Relationship, Target
+from .version import __version__
+
+__all__ = ["Client", "check", "async_check", "Configuration", "load_config", "CheckEntry",
+           "CheckReport", "HealthResult", "HealthStatus", "Relationship", "Target",
+           "AgentHealthError", "BinaryNotFoundError", "CheckTimeoutError", "CompatibilityError",
+           "ConfigurationError", "ExecutionError", "OutputError", "__version__"]

agenthealth-0.13.2/src/agenthealth/client.py

@@ -0,0 +1,199 @@
+"""Bounded CLI execution with native async cancellation and no shell invocation."""
+import asyncio
+from contextlib import contextmanager
+import json
+import math
+import os
+import re
+from pathlib import Path
+import shutil
+import signal
+import tempfile
+import time
+from typing import Any, Mapping, Sequence
+
+from .config import Configuration, load_config
+from .errors import (BinaryNotFoundError, CheckTimeoutError, CompatibilityError,
+                     ConfigurationError, ExecutionError, OutputError)
+from .models import CheckReport, parse_report
+from .version import __version__
+
+MAX_OUTPUT_BYTES = 16 * 1024 * 1024
+MAX_DIAGNOSTIC_BYTES = 64 * 1024
+
+
+async def _signal_group(process: asyncio.subprocess.Process, sig: int) -> None:
+    try:
+        os.killpg(process.pid, sig)
+    except ProcessLookupError:
+        pass
+    except PermissionError:
+        # Darwin can report EPERM for an already-exited process group. Confirm
+        # root exit before accepting it; a live permission failure remains fatal.
+        if process.returncode is None:
+            try:
+                await asyncio.wait_for(process.wait(), 1)
+            except asyncio.TimeoutError:
+                raise ExecutionError("Unable to stop AgentHealth CLI process") from None
+
+
+async def _stop(process: asyncio.subprocess.Process) -> None:
+    # Kill the dedicated process group even if the root exited, so an MCP stdio
+    # descendant cannot retain credentials or the temporary output descriptors.
+    try:
+        if os.name == "posix":
+            await _signal_group(process, signal.SIGTERM)
+        elif process.returncode is None:
+            process.terminate()
+    except ProcessLookupError:
+        pass
+    try:
+        await asyncio.wait_for(process.wait(), 1)
+    except asyncio.TimeoutError:
+        pass
+    finally:
+        try:
+            if os.name == "posix":
+                await _signal_group(process, signal.SIGKILL)
+            elif process.returncode is None:
+                process.kill()
+        except ProcessLookupError:
+            pass
+        await process.wait()
+
+
+async def _run(command: list[str], *, timeout: float, cwd: Path,
+               environment: Mapping[str, str] | None) -> tuple[int, bytes]:
+    env = None if environment is None else {**os.environ, **environment}
+    with tempfile.TemporaryFile() as output, tempfile.TemporaryFile() as diagnostic:
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *command, stdin=asyncio.subprocess.DEVNULL, stdout=output, stderr=diagnostic,
+                cwd=cwd, env=env, start_new_session=os.name == "posix")
+        except OSError:
+            raise BinaryNotFoundError("Unable to start AgentHealth CLI") from None
+        deadline = time.monotonic() + timeout
+        try:
+            while True:
+                if (os.fstat(output.fileno()).st_size > MAX_OUTPUT_BYTES or
+                        os.fstat(diagnostic.fileno()).st_size > MAX_DIAGNOSTIC_BYTES):
+                    raise OutputError("AgentHealth output exceeded the SDK limit")
+                if process.returncode is not None:
+                    break
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise CheckTimeoutError("AgentHealth check deadline expired")
+                await asyncio.sleep(min(0.02, remaining))
+            output.seek(0)
+            return process.returncode, output.read(MAX_OUTPUT_BYTES + 1)
+        finally:
+            # A separate task keeps cleanup alive if another cancellation arrives.
+            cleanup = asyncio.create_task(_stop(process))
+            try:
+                await asyncio.shield(cleanup)
+            except asyncio.CancelledError:
+                await cleanup
+                raise
+
+
+@contextmanager
+def _config_file(configuration: Configuration):
+    with tempfile.TemporaryDirectory(prefix="agenthealth-sdk-") as directory:
+        path = Path(directory) / "configuration.json"
+        # Directory mode is 0700; file is never passed in command text or stderr.
+        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(descriptor, "w") as stream:
+            json.dump(configuration.to_dict(), stream, allow_nan=False)
+        yield path
+
+
+def _configuration(config: Configuration | Mapping[str, Any] | str | Path | None,
+                   target_type: str | None, endpoint: str | None, name: str,
+                   checks: Sequence[str] | None, options: Mapping[str, Any] | None) -> Configuration:
+    if config is not None:
+        if target_type is not None or endpoint is not None or checks is not None or options is not None:
+            raise ConfigurationError("Choose a configuration or individual target arguments")
+        if isinstance(config, Configuration):
+            return config
+        if isinstance(config, Mapping):
+            return Configuration(config)
+        return load_config(config)
+    if target_type is None or endpoint is None:
+        raise ConfigurationError("A configuration or target_type and endpoint are required")
+    target: dict[str, Any] = dict(options or {})
+    if any(key in target for key in ("name", "type", "endpoint", "checks")):
+        raise ConfigurationError("Target options must not override named arguments")
+    target.update(name=name, type=target_type, endpoint=endpoint)
+    if checks is not None:
+        target["checks"] = list(checks)
+    return Configuration({"version": "v1", "targets": [target]})
+
+
+class Client:
+    """Use an installed CLI of exactly the SDK version; never download or execute
+    a binary at import/install time. Pass a verified binary path when pinning it.
+    """
+
+    def __init__(self, binary: str | Path = "agenthealth", *, timeout: float = 30,
+                 environment: Mapping[str, str] | None = None):
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be a positive finite number")
+        self.binary = str(binary)
+        self.timeout = timeout
+        self.environment = None if environment is None else dict(environment)
+
+    async def async_check(self, config: Configuration | Mapping[str, Any] | str | Path | None = None,
+                          *, target_type: str | None = None, endpoint: str | None = None,
+                          name: str = "target", checks: Sequence[str] | None = None,
+                          options: Mapping[str, Any] | None = None) -> CheckReport:
+        configuration = _configuration(config, target_type, endpoint, name, checks, options)
+        # Resolve before changing cwd; relative explicit binary paths retain their meaning.
+        binary = shutil.which(self.binary)
+        if binary is None:
+            raise BinaryNotFoundError("AgentHealth CLI executable was not found")
+        binary = str(Path(binary).resolve())
+        deadline = time.monotonic() + self.timeout
+        code, version = await _run([binary, "version"], timeout=min(self.timeout, 5),
+                                   cwd=configuration.base_dir, environment=self.environment)
+        cli_version = re.sub(r"(a|b|rc)([0-9]+)$", r"-\1.\2", __version__)
+        if code != 0 or version.strip() != f"agenthealth v{cli_version}".encode():
+            raise CompatibilityError("AgentHealth CLI must match the SDK software version")
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise CheckTimeoutError("AgentHealth check deadline expired")
+        with _config_file(configuration) as path:
+            code, output = await _run([binary, "check", "--format", "json", "--", str(path)],
+                                      timeout=remaining, cwd=configuration.base_dir,
+                                      environment=self.environment)
+        if code not in range(6):
+            raise ExecutionError("AgentHealth CLI execution failed")
+        return parse_report(output, code)
+
+    def check(self, config: Configuration | Mapping[str, Any] | str | Path | None = None,
+              *, target_type: str | None = None, endpoint: str | None = None,
+              name: str = "target", checks: Sequence[str] | None = None,
+              options: Mapping[str, Any] | None = None) -> CheckReport:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(self.async_check(config, target_type=target_type, endpoint=endpoint,
+                                                name=name, checks=checks, options=options))
+        raise RuntimeError("Use await client.async_check() inside an event loop")
+
+
+def check(config: Configuration | Mapping[str, Any] | str | Path | None = None, *,
+          target_type: str | None = None, endpoint: str | None = None, name: str = "target",
+          checks: Sequence[str] | None = None, options: Mapping[str, Any] | None = None,
+          binary: str | Path = "agenthealth", timeout: float = 30,
+          environment: Mapping[str, str] | None = None) -> CheckReport:
+    return Client(binary, timeout=timeout, environment=environment).check(
+        config, target_type=target_type, endpoint=endpoint, name=name, checks=checks, options=options)
+
+
+async def async_check(config: Configuration | Mapping[str, Any] | str | Path | None = None, *,
+                      target_type: str | None = None, endpoint: str | None = None, name: str = "target",
+                      checks: Sequence[str] | None = None, options: Mapping[str, Any] | None = None,
+                      binary: str | Path = "agenthealth", timeout: float = 30,
+                      environment: Mapping[str, str] | None = None) -> CheckReport:
+    return await Client(binary, timeout=timeout, environment=environment).async_check(
+        config, target_type=target_type, endpoint=endpoint, name=name, checks=checks, options=options)

agenthealth-0.13.2/src/agenthealth/config.py

@@ -0,0 +1,71 @@
+"""Load trusted configuration without executing checks or resolving credentials."""
+from copy import deepcopy
+from importlib.resources import files
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+from jsonschema import Draft202012Validator
+import yaml
+
+from .errors import ConfigurationError
+
+MAX_CONFIG_BYTES = 4 * 1024 * 1024
+
+
+def validator(name: str) -> Draft202012Validator:
+    schema = json.loads(files("agenthealth").joinpath("schemas", name + ".schema.json").read_text())
+    return Draft202012Validator(schema)
+
+
+class Configuration:
+    """A validated copy of an AHS v1 document; semantic validation stays in Go."""
+
+    def __init__(self, data: Mapping[str, Any], *, base_dir: str | Path | None = None):
+        try:
+            document = json.loads(json.dumps(dict(data), allow_nan=False))
+            validator("configuration").validate(document)
+            if len(json.dumps(document).encode()) > MAX_CONFIG_BYTES:
+                raise ValueError()
+        except Exception:
+            # Schema/parser exceptions may contain credentials and configured values.
+            raise ConfigurationError("Invalid AgentHealth configuration") from None
+        self._data = document
+        self.base_dir = Path(base_dir).resolve() if base_dir is not None else Path.cwd()
+
+    def to_dict(self) -> dict[str, Any]:
+        return deepcopy(self._data)
+
+
+class _UniqueLoader(yaml.SafeLoader):
+    pass
+
+
+def _mapping(loader: _UniqueLoader, node: yaml.MappingNode, deep: bool = False):
+    result = {}
+    for key_node, value_node in node.value:
+        key = loader.construct_object(key_node, deep=deep)
+        if key in result:
+            raise ValueError("Duplicate YAML key")
+        result[key] = loader.construct_object(value_node, deep=deep)
+    return result
+
+
+_UniqueLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _mapping)
+
+
+def load_config(path: str | Path) -> Configuration:
+    """Read bounded JSON/YAML. Relative credential/token paths use the caller's cwd,
+    matching CLI behavior. Pass base_dir explicitly to Configuration to change it.
+    """
+    try:
+        with Path(path).open("rb") as stream:
+            data = stream.read(MAX_CONFIG_BYTES + 1)
+        if len(data) > MAX_CONFIG_BYTES:
+            raise ValueError()
+        document = yaml.load(data, Loader=_UniqueLoader)
+        if not isinstance(document, dict):
+            raise ValueError()
+        return Configuration(document)
+    except Exception:
+        raise ConfigurationError("Unable to load AgentHealth configuration") from None

agenthealth-0.13.2/src/agenthealth/errors.py

@@ -0,0 +1,29 @@
+"""Tool failures are exceptions; health failures remain results."""
+
+
+class AgentHealthError(Exception):
+    """Base class for SDK/tool errors. Messages never include CLI diagnostics."""
+
+
+class ConfigurationError(AgentHealthError):
+    """Unreadable or invalid SDK configuration."""
+
+
+class BinaryNotFoundError(AgentHealthError):
+    """The requested CLI executable could not be started."""
+
+
+class CompatibilityError(AgentHealthError):
+    """The CLI software version does not match the SDK."""
+
+
+class ExecutionError(AgentHealthError):
+    """The CLI failed to execute or returned exit code 6."""
+
+
+class CheckTimeoutError(AgentHealthError):
+    """The SDK deadline expired; the CLI was stopped."""
+
+
+class OutputError(AgentHealthError):
+    """The CLI returned oversized or invalid machine output."""