fairmind 0.3.1a0__py3-none-any.whl

fairmind/__init__.py

@@ -0,0 +1,31 @@
+"""Typed Python client for FairMind."""
+
+__version__ = "0.3.1a0"
+
+from .client import FairMind, FairMindError  # noqa: E402
+from .types import (  # noqa: E402
+    Attestation,
+    Clause,
+    ClauseMap,
+    FairnessRun,
+    Framework,
+    Gate,
+    GateCheck,
+    MonitoringRun,
+    System,
+)
+
+__all__ = [
+    "FairMind",
+    "FairMindError",
+    "Attestation",
+    "Clause",
+    "ClauseMap",
+    "FairnessRun",
+    "Framework",
+    "Gate",
+    "GateCheck",
+    "MonitoringRun",
+    "System",
+    "__version__",
+]

fairmind/client.py

@@ -0,0 +1,247 @@
+"""HTTP client for the FairMind API. Mirrors the conventions of the fairmind CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from contextlib import ExitStack
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+import httpx
+
+from . import __version__
+from .types import Attestation, AttestableCheck, ClauseMap, FairnessRun, Gate, MonitoringRun, System
+
+GOV = "/api/v1/ai-governance"
+PACKS = "/api/v1/packs"
+DEFAULT_API_URL = "http://localhost:8010"
+
+# legacy framework ids -> catalogue keys, as accepted by the report request
+_FRAMEWORK_ALIASES = {"eu_ai_act": "EUAIA", "iso_42001": "ISO42001", "nist_ai_rmf": "NISTRMF", "india_ai": "INDAI"}
+
+PathLike = Union[str, "os.PathLike[str]"]
+
+
+class FairMindError(Exception):
+    """A failed call. `status_code` is None when the server could not be reached."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+    def __str__(self) -> str:
+        return f"{self.status_code}: {self.message}" if self.status_code else self.message
+
+
+def _split(value: Union[str, Sequence[str]]) -> str:
+    return value if isinstance(value, str) else ",".join(value)
+
+
+class FairMind:
+    """`FairMind(api_url=None, api_key=None)`; FAIRMIND_API_URL and FAIRMIND_API_KEY are read when omitted."""
+
+    def __init__(
+        self,
+        api_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        *,
+        timeout: Union[float, httpx.Timeout] = httpx.Timeout(180.0, connect=10.0),
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self.api_url = (api_url or os.environ.get("FAIRMIND_API_URL") or DEFAULT_API_URL).rstrip("/")
+        key = api_key or os.environ.get("FAIRMIND_API_KEY") or ""
+        headers = {"Accept": "application/json", "User-Agent": f"fairmind-sdk/{__version__}"}
+        if key:
+            headers["Authorization"] = f"Bearer {key}"
+        self._http = httpx.Client(base_url=self.api_url, headers=headers, timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "FairMind":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # -- transport -----------------------------------------------------------
+
+    def _call(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = self._http.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise FairMindError(f"Could not reach FairMind at {self.api_url}: {exc}") from exc
+        code = response.status_code
+        if code == 401:
+            raise FairMindError("Not signed in. Set FAIRMIND_API_KEY to a key from POST /api/v1/auth/api-keys.", code)
+        if code >= 400:
+            try:
+                body = response.json()
+                detail = body.get("detail") or body.get("message") or response.text
+            except (ValueError, AttributeError):
+                detail = response.text
+            if code == 404:
+                detail = f"Not found: {path}. Check the system id and that your key belongs to its organisation. {detail}"
+            raise FairMindError(f"{method} {path} failed: {detail}", code)
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise FairMindError(f"{method} {path} returned something that is not JSON", code) from exc
+
+    def _upload(self, path: str, csv_path: PathLike, data: Dict[str, str]) -> Any:
+        p = Path(csv_path)
+        if not p.is_file():
+            raise FairMindError(f"No such file: {p}")
+        with p.open("rb") as handle:
+            return self._call("POST", path, data=data, files={"file": (p.name, handle, "text/csv")})
+
+    # -- reads ---------------------------------------------------------------
+
+    def systems(self) -> List[System]:
+        return self._call("GET", f"{GOV}/systems")
+
+    def gate(self, system_id: str) -> Gate:
+        return self._call("GET", f"{GOV}/systems/{system_id}/gate")
+
+    def clause_map(self, system_id: str, frameworks: Optional[Sequence[str]] = None) -> ClauseMap:
+        """The gate read per framework clause. `frameworks` filters client-side by catalogue key (EUAIA, ISO42001, ...)."""
+        result = self._call("GET", f"{GOV}/systems/{system_id}/clause-map")
+        if frameworks:
+            wanted = {_FRAMEWORK_ALIASES.get(f.lower(), f).upper() for f in frameworks}
+            result["frameworks"] = [f for f in result["frameworks"] if f["key"].upper() in wanted]
+        return result
+
+    def seals(self, system_id: str) -> List[Dict[str, Any]]:
+        return self._call("GET", f"{GOV}/systems/{system_id}/seals")
+
+    def fairness_runs(self, system_id: str) -> List[Dict[str, Any]]:
+        return self._call("GET", f"{GOV}/systems/{system_id}/fairness-runs")
+
+    def monitoring_runs(self, system_id: str) -> List[Dict[str, Any]]:
+        return self._call("GET", f"{GOV}/systems/{system_id}/monitoring-runs")
+
+    # -- writes --------------------------------------------------------------
+
+    def inspect_csv(self, system_id: str, path: PathLike) -> Dict[str, Any]:
+        """Columns of a CSV with sample values and a suggested outcome/prediction/score/attributes mapping."""
+        return self._upload(f"{GOV}/systems/{system_id}/fairness-runs/inspect", path, {})
+
+    def run_fairness(
+        self,
+        system_id: str,
+        path: PathLike,
+        *,
+        outcome: str,
+        attributes: Union[str, Sequence[str]],
+        prediction: Optional[str] = None,
+        score: Optional[str] = None,
+        favorable_label: Optional[str] = None,
+    ) -> FairnessRun:
+        if not prediction and not score:
+            raise FairMindError("Give prediction (a 0/1 column) or score (a 0 to 1 column)")
+        data = {"outcome": outcome, "attributes": _split(attributes)}
+        for key, value in (("prediction", prediction), ("score", score), ("favorable_label", favorable_label)):
+            if value:
+                data[key] = value
+        return self._upload(f"{GOV}/systems/{system_id}/fairness-runs", path, data)
+
+    def run_monitoring(
+        self,
+        system_id: str,
+        path: PathLike,
+        *,
+        attributes: Union[str, Sequence[str]],
+        prediction: Optional[str] = None,
+        score: Optional[str] = None,
+        favorable_label: Optional[str] = None,
+    ) -> MonitoringRun:
+        if not prediction and not score:
+            raise FairMindError("Give prediction (a 0/1 column) or score (a 0 to 1 column)")
+        data = {"attributes": _split(attributes)}
+        for key, value in (("prediction", prediction), ("score", score), ("favorable_label", favorable_label)):
+            if value:
+                data[key] = value
+        return self._upload(f"{GOV}/systems/{system_id}/monitoring-runs", path, data)
+
+    def attest(self, system_id: str, check: AttestableCheck, statement: str, reference: Optional[str] = None) -> Attestation:
+        """Record that a person states a gate check is satisfied. Manual provenance: it attests, it never proves."""
+        body: Dict[str, Any] = {"check": check, "statement": statement}
+        if reference:
+            body["reference"] = reference
+        return self._call("POST", f"{GOV}/systems/{system_id}/attestations", json=body)
+
+    # -- catalogue evaluations ---------------------------------------------
+
+    def organization_id(self) -> str:
+        """The organisation the evaluation endpoints act in: FAIRMIND_ORG_ID, else the key's first organisation."""
+        if not getattr(self, "_org_id", None):
+            org = os.environ.get("FAIRMIND_ORG_ID")
+            if not org:
+                orgs = self._call("GET", "/api/v1/organizations").get("organizations") or []
+                if not orgs:
+                    raise FairMindError("This key belongs to no organisation")
+                org = orgs[0]["id"]
+            self._org_id = org
+        return self._org_id
+
+    def _packs(self, method: str, path: str, **kwargs: Any) -> Any:
+        params = {**kwargs.pop("params", {}), "org_id": self.organization_id()}
+        return self._call(method, f"{PACKS}{path}", params=params, **kwargs)
+
+    def evaluations(self, query: Optional[str] = None, pillar: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Catalogue evaluations; `runnable` is true for those FairMind computes itself."""
+        params = {k: v for k, v in (("q", query), ("pillar", pillar)) if v}
+        return self._packs("GET", "/evaluations", params=params)
+
+    def evaluation_engine(self, evaluation_id: str) -> Dict[str, Any]:
+        """The files (slots) and params an evaluation takes, and its live alternate if it has one."""
+        return self._packs("GET", f"/evaluations/{evaluation_id}/engine")
+
+    def evaluation_runs(self, evaluation_id: str, system_id: Optional[str] = None) -> List[Dict[str, Any]]:
+        params = {"system_id": system_id} if system_id else {}
+        return self._packs("GET", f"/evaluations/{evaluation_id}/runs", params=params)
+
+    def run_evaluation(
+        self,
+        system_id: str,
+        evaluation_id: str,
+        files: Optional[Dict[str, PathLike]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        live: bool = False,
+        source: str = "upload",
+        timeout: float = 900.0,
+        poll_interval: float = 3.0,
+    ) -> Dict[str, Any]:
+        """Run a catalogue evaluation and return the stored run (status passed, failed or insufficient, metrics, detail).
+
+        `files` maps the engine's slot names to local paths. `live=True` runs the evaluation's behaviour test
+        against the system's connected endpoint; `source="connection"` reads the organisation's agent platform.
+        Behaviour tests run as background jobs on the server; this waits for them up to `timeout` seconds.
+        """
+        data = {"system_id": system_id, "params": json.dumps(params or {}), "source": source}
+        if live:
+            data["mode"] = "live"
+        with ExitStack() as stack:
+            uploads = {}
+            for slot, path in (files or {}).items():
+                p = Path(path)
+                if not p.is_file():
+                    raise FairMindError(f"No such file: {p}")
+                uploads[slot] = (p.name, stack.enter_context(p.open("rb")))
+            result = self._packs("POST", f"/evaluations/{evaluation_id}/runs", data=data, files=uploads or None)
+        job = result.get("job") if isinstance(result, dict) else None
+        if not job:
+            return result
+        deadline = time.monotonic() + timeout
+        while job["status"] not in ("done", "failed"):
+            if time.monotonic() > deadline:
+                raise FairMindError(f"Evaluation job {job['id']} is still running after {timeout:.0f}s; check it later")
+            time.sleep(poll_interval)
+            job = self._packs("GET", f"/evaluation-jobs/{job['id']}")
+        if job["status"] == "failed":
+            raise FairMindError(f"Evaluation {evaluation_id} failed: {job.get('error') or 'no reason given'}")
+        return self._packs("GET", f"/evaluation-runs/{job['evidenceId']}")

fairmind/types.py

@@ -0,0 +1,102 @@
+"""Response shapes, as the API returns them (camelCase keys where the API uses them)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict
+
+Verdict = Literal["go", "conditional_go", "no_go"]
+ApprovalStatus = Literal["not_requested", "pending", "approved", "rejected"]
+CheckState = Literal["proven", "attested", "open"]
+AttestableCheck = Literal["data_governance", "human_oversight", "monitoring", "environmental"]
+
+
+class System(TypedDict, total=False):
+    id: str
+    name: str
+    owner: str
+    riskTier: str
+    lifecycleStage: str
+    workspaceId: str
+
+
+class GateCheck(TypedDict):
+    key: str
+    label: str
+    state: CheckState
+    confidence: float
+    evidenceId: Optional[str]
+    detail: Optional[Dict[str, Any]]
+
+
+class Gate(TypedDict, total=False):
+    verdict: Verdict
+    confidence: float
+    band: str
+    checks: List[GateCheck]
+    reasons: List[str]
+    proven: int
+    attested: int
+    open: int
+    systemId: str
+    riskTier: str
+    approvalStatus: ApprovalStatus  # latest release decision; "rejected" forces verdict no_go
+
+
+class ClauseCheck(TypedDict):
+    check: str
+    label: str
+    state: CheckState
+    confidence: float
+    evidenceId: Optional[str]
+    relation: str
+
+
+class Clause(TypedDict):
+    key: str
+    control: str
+    title: str
+    group: Optional[str]
+    checks: List[ClauseCheck]
+    state: CheckState
+
+
+class Framework(TypedDict):
+    key: str
+    name: str
+    clauses: List[Clause]
+    counts: Dict[str, int]
+
+
+class ClauseMap(TypedDict):
+    verdict: Verdict
+    confidence: float
+    frameworks: List[Framework]
+    systemId: str
+
+
+class FairnessRun(TypedDict):
+    """Result of POST /fairness-runs. `result` holds per-attribute metrics and `all_checks_pass`."""
+
+    runId: str
+    evidenceId: str
+    systemId: str
+    title: str
+    result: Dict[str, Any]
+    gate: Gate
+
+
+class MonitoringRun(TypedDict):
+    """Result of POST /monitoring-runs. `result` holds drift, impact ratio and score PSI per attribute."""
+
+    evidenceId: str
+    systemId: str
+    title: str
+    result: Dict[str, Any]
+    gate: Gate
+
+
+class Attestation(TypedDict):
+    evidenceId: str
+    systemId: str
+    check: AttestableCheck
+    gate: Gate

fairmind-0.3.1a0.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.5
+Name: fairmind
+Version: 0.3.1a0
+Summary: Typed Python client for FairMind: release gate, fairness tests, monitoring and attestations.
+Author-email: Adhithya Rajasekaran <adhithya@axonome.xyz>
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# fairmind (Python SDK)
+
+A small typed client for the FairMind API: read the release gate, run fairness tests, record monitoring snapshots and attestations. One dependency, `httpx`.
+
+```bash
+pip install ./apps/sdk        # from a checkout; or: uv add ./apps/sdk
+export FAIRMIND_API_URL=https://fairmind.example.com
+export FAIRMIND_API_KEY=...   # minted at POST /api/v1/auth/api-keys
+```
+
+```python
+from fairmind import FairMind, FairMindError
+
+fm = FairMind()  # reads FAIRMIND_API_URL and FAIRMIND_API_KEY
+
+system = fm.systems()[0]["id"]
+run = fm.run_fairness(system, "predictions.csv", outcome="repaid", prediction="approved", attributes=["gender", "region"])
+gate = run["gate"]
+print(gate["verdict"], gate["confidence"])
+for check in gate["checks"]:
+    print(check["label"], check["state"])
+```
+
+## Methods
+
+| Method | Endpoint |
+| --- | --- |
+| `systems()` | `GET /systems` |
+| `gate(system_id)` | `GET /systems/{id}/gate` |
+| `clause_map(system_id, frameworks=None)` | `GET /systems/{id}/clause-map`; `frameworks` (for example `["EUAIA", "ISO42001"]`) filters the result |
+| `seals(system_id)` | `GET /systems/{id}/seals` |
+| `inspect_csv(system_id, path)` | `POST /systems/{id}/fairness-runs/inspect` |
+| `run_fairness(system_id, path, *, outcome, attributes, prediction=None, score=None, favorable_label=None)` | `POST /systems/{id}/fairness-runs` |
+| `fairness_runs(system_id)` | `GET /systems/{id}/fairness-runs` |
+| `run_monitoring(system_id, path, *, attributes, prediction=None, score=None, favorable_label=None)` | `POST /systems/{id}/monitoring-runs` |
+| `monitoring_runs(system_id)` | `GET /systems/{id}/monitoring-runs` |
+| `attest(system_id, check, statement, reference=None)` | `POST /systems/{id}/attestations` |
+| `evaluations(query=None, pillar=None)` | `GET /api/v1/packs/evaluations` |
+| `evaluation_engine(evaluation_id)` | `GET /api/v1/packs/evaluations/{id}/engine`: the files and params it takes |
+| `run_evaluation(system_id, evaluation_id, files=None, params=None, live=False, source="upload")` | `POST /api/v1/packs/evaluations/{id}/runs`; waits for behaviour-test jobs and returns the stored run |
+| `evaluation_runs(evaluation_id, system_id=None)` | `GET /api/v1/packs/evaluations/{id}/runs` |
+
+The evaluation methods act in the organisation from `FAIRMIND_ORG_ID`, or the key's first organisation when it is unset.
+
+`attributes` is a list or a comma-separated string. `run_fairness` and `run_monitoring` need `prediction` (a 0/1 column) or `score` (a 0 to 1 column). Responses are plain dicts typed with `TypedDict`s (`Gate`, `GateCheck`, `ClauseMap`, `FairnessRun`, `MonitoringRun`, ...).
+
+Every failure raises `FairMindError` with `status_code` (`None` when the server could not be reached) and `message` (the server's `detail` when it sent one).
+
+## Tests
+
+```bash
+cd apps/sdk && uv run --with pytest pytest -q -p no:cacheprovider tests
+```

fairmind-0.3.1a0.dist-info/RECORD

@@ -0,0 +1,6 @@
+fairmind/__init__.py,sha256=TTE4AQr_EJvAmSO9773u9idfSg5-wP8MfHuPhWEekxc,514
+fairmind/client.py,sha256=io29ARGfzcy4OLUHp7x-BcLOz6Z4NwkNf9CMs-J0wcA,11278
+fairmind/types.py,sha256=w5DVPEDO379fdeIEfXm0eXRL2ru4n67DkhV1Y_NXfZg,2233
+fairmind-0.3.1a0.dist-info/METADATA,sha256=1DTgv0GJvRFfbbReXNY6Y4g-brsLLXwGRe87CzKlrOs,3205
+fairmind-0.3.1a0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+fairmind-0.3.1a0.dist-info/RECORD,,

fairmind-0.3.1a0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any