fairmind 0.3.1a0__tar.gz

fairmind-0.3.1a0/.gitignore

@@ -0,0 +1,366 @@
+# Internal planning docs (local only)
+TODO_DEEP_ANALYSIS.md
+
+# Dependencies
+node_modules/
+junk/
+.pnp
+.pnp.js
+
+# Testing
+coverage/
+.nyc_output
+
+# Next.js
+.next/
+out/
+build/
+dist/
+
+# Production
+build/
+
+# Misc
+.DS_Store
+*.pem
+*.p12
+*.key
+*.pfx
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Local env files
+.env
+.env*.local
+.env.development.local
+.env.test.local
+.env.production.local
+.env.prisma
+
+# Vercel
+.vercel
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+# Python lib directories (but not frontend src/lib)
+/lib/
+/lib64/
+apps/backend/lib/
+apps/backend/lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+/WORKSPACE_CLEANUP_SUMMARY.md
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Security & Secrets
+*.pem
+*.key
+*.p12
+*.pfx
+*.crt
+*.csr
+*.pem
+private_key*
+public_key*
+id_rsa*
+id_dsa*
+id_ecdsa*
+id_ed25519*
+*.env
+.env*
+secrets*
+config/secrets*
+credentials*
+
+# JSON files (but allow important config files)
+*.json
+# fumadocs section indexes order the docs navigation; they are source, not data.
+!apps/docs/content/**/meta.json
+!package.json
+!package-lock.json
+!research/aibom-fairness-evidence/**/*.json
+!apps/backend/src/domain/assurance/evidence-passport-v2.schema.json
+!apps/backend/src/api/routers/pack_catalogue_data/*.json
+!apps/backend/reference_data/frameworks/*.json
+!apps/eval-runner/seccomp/sandbox.json
+!tsconfig.json
+!next.config.js
+!tailwind.config.ts
+!postcss.config.js
+!eslint.config.js
+!babel.config.js
+!jest.config.js
+!vite.config.js
+!rollup.config.js
+!webpack.config.js
+!metro.config.js
+!bunfig.toml
+!pyproject.toml
+!setup.py
+!requirements.txt
+!Pipfile
+!Pipfile.lock
+!poetry.lock
+!Cargo.toml
+!Cargo.lock
+!go.mod
+!go.sum
+!composer.json
+!composer.lock
+!Gemfile
+!Gemfile.lock
+!yarn.lock
+!pnpm-lock.yaml
+!bun.lockb
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+*.db-journal
+
+# Logs
+*.log
+logs/
+
+# IDE
+.vscode/
+.idea/
+
+# Local/external nested repositories (never track in this repo)
+.claude/worktrees/
+.wiki/
+_external/
+apps/backend/src/domain/bias/bias_bench_repo/
+apps/backend/uploads/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+*.bak
+*.backup
+*.orig
+
+# Large files
+*.zip
+*.tar.gz
+*.rar
+*.7z
+*.iso
+*.dmg
+*.pkg
+*.deb
+*.rpm
+*.msi
+*.exe
+*.dll
+*.so
+*.dylib
+*.bin
+
+# Model files (large ML models)
+*.pkl
+*.joblib
+*.h5
+*.hdf5
+*.onnx
+*.pb
+*.pt
+*.pth
+*.safetensors
+*.tflite
+*.mlmodel
+models/
+checkpoints/
+
+# Data files
+*.csv
+!research/aibom-fairness-evidence/**/*.csv
+*.xml
+*.yaml
+*.yml
+# GitHub workflows and composite actions are source.
+!.github/**/*.yml
+!.github/**/*.yaml
+data/
+datasets/
+*.parquet
+*.feather
+*.hdf
+*.h5
+*.nc
+*.netcdf
+
+# Cache
+.cache/
+cache/
+tmp/
+temp/
+
+# Specific security-sensitive files
+localhost.har
+*.har
+apps/backend/public_key.pem
+
+# The broad ML artifact rule ``models/`` must not hide active API source.
+# Re-including the directory still leaves *.pt, *.pkl etc. ignored inside it.
+!apps/backend/api/models/
+!apps/backend/api/models/**/*.py
+!apps/backend/src/**/models/
+apps/backend/private_key.pem
+apps/backend/api/services/real_bias_detection_service.py
+apps/backend/email_service.py
+apps/backend/neo4j_integration.py
+apps/frontend/src/app/\(auth\)/signup/page.tsx
+apps/website/bun.lock
+apps/website/src/content/docs/installation.mdx
+
+# Local Netlify folder
+.netlify
+
+# Archive directory
+archive/
+neura-dash-backup/
+
+.qoder/
+
+# Playwright test artifacts
+.playwright-mcp/
+playwright-report/
+test-results/
+
+# Screenshots and images (except logo and issue screenshots)
+*.png
+!**/public/logo.png
+!**/logo.png
+!docs/assets/issues/*.png
+!assets/logo/*.png
+!assets/diagrams/*.png
+
+# Temporary documentation files
+.temp-docs/
+
+# Frontend archive (preserved for reference)
+apps/frontend-archive/
+apps/frontend-archive/node_modules/
+apps/frontend-archive/.next/
+apps/frontend-archive/out/
+apps/frontend-archive/build/
+apps/frontend-archive/dist/
+
+# graft's local graph cache: regenerable, not committed (run `graft build`).
+/graft/

fairmind-0.3.1a0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,53 @@
+# 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/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "fairmind"
+version = "0.3.1a0"
+description = "Typed Python client for FairMind: release gate, fairness tests, monitoring and attestations."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Adhithya Rajasekaran", email = "adhithya@axonome.xyz" }]
+dependencies = ["httpx>=0.27"]
+
+[dependency-groups]
+dev = ["pytest>=7.4"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fairmind"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fairmind-0.3.1a0/src/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-0.3.1a0/src/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-0.3.1a0/src/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/tests/test_client.py

@@ -0,0 +1,181 @@
+import json
+
+import httpx
+import pytest
+
+from fairmind import FairMind, FairMindError
+
+GOV = "/api/v1/ai-governance"
+
+
+def make(handler, **kwargs):
+    return FairMind(api_url="http://fm.test/", api_key="k", transport=httpx.MockTransport(handler), **kwargs)
+
+
+def test_auth_header_and_base_url():
+    seen = {}
+
+    def handler(request):
+        seen["url"], seen["auth"] = str(request.url), request.headers["authorization"]
+        return httpx.Response(200, json=[])
+
+    assert make(handler).systems() == []
+    assert seen == {"url": f"http://fm.test{GOV}/systems", "auth": "Bearer k"}
+
+
+def test_env_defaults(monkeypatch):
+    monkeypatch.setenv("FAIRMIND_API_URL", "http://env.test")
+    monkeypatch.setenv("FAIRMIND_API_KEY", "envkey")
+    client = FairMind()
+    assert client.api_url == "http://env.test"
+    assert client._http.headers["authorization"] == "Bearer envkey"
+
+
+def test_gate_and_error_carries_status_and_detail():
+    def handler(request):
+        if request.url.path.endswith("/s1/gate"):
+            return httpx.Response(200, json={"verdict": "go"})
+        return httpx.Response(403, json={"detail": "read only key"})
+
+    fm = make(handler)
+    assert fm.gate("s1")["verdict"] == "go"
+    with pytest.raises(FairMindError) as err:
+        fm.gate("s2")
+    assert err.value.status_code == 403 and "read only key" in err.value.message
+
+
+def test_401_and_404_messages():
+    fm = make(lambda r: httpx.Response(401 if "a" in r.url.path.split("/")[-2] else 404, json={"detail": "x"}))
+    with pytest.raises(FairMindError, match="FAIRMIND_API_KEY") as err:
+        fm.gate("a")
+    assert err.value.status_code == 401
+    with pytest.raises(FairMindError, match="Not found") as err:
+        fm.gate("zz")
+    assert err.value.status_code == 404
+
+
+def test_network_failure_has_no_status():
+    def handler(request):
+        raise httpx.ConnectError("refused")
+
+    with pytest.raises(FairMindError, match="Could not reach") as err:
+        make(handler).systems()
+    assert err.value.status_code is None
+
+
+def test_clause_map_filters_frameworks():
+    payload = {"verdict": "go", "confidence": 0.9, "frameworks": [{"key": "EUAIA"}, {"key": "ISO42001"}, {"key": "GDPR"}]}
+    fm = make(lambda r: httpx.Response(200, json=json.loads(json.dumps(payload))))
+    assert [f["key"] for f in fm.clause_map("s")["frameworks"]] == ["EUAIA", "ISO42001", "GDPR"]
+    assert [f["key"] for f in fm.clause_map("s", frameworks=["eu_ai_act", "GDPR"])["frameworks"]] == ["EUAIA", "GDPR"]
+
+
+def test_run_fairness_sends_multipart(tmp_path):
+    csv = tmp_path / "p.csv"
+    csv.write_text("y,p,g\n1,1,a\n")
+    seen = {}
+
+    def handler(request):
+        seen["path"], seen["body"] = request.url.path, request.content.decode()
+        return httpx.Response(200, json={"runId": "r"})
+
+    out = make(handler).run_fairness("s1", csv, outcome="y", prediction="p", attributes=["g", "h"], favorable_label="1")
+    assert out["runId"] == "r"
+    assert seen["path"] == f"{GOV}/systems/s1/fairness-runs"
+    for needle in ('name="outcome"', "\r\ny\r\n", "g,h", 'name="favorable_label"', 'filename="p.csv"', "y,p,g"):
+        assert needle in seen["body"]
+    assert 'name="score"' not in seen["body"]
+
+
+def test_run_requires_prediction_or_score_and_existing_file(tmp_path):
+    fm = make(lambda r: httpx.Response(200, json={}))
+    csv = tmp_path / "p.csv"
+    csv.write_text("a\n1\n")
+    with pytest.raises(FairMindError, match="prediction"):
+        fm.run_fairness("s", csv, outcome="y", attributes="g")
+    with pytest.raises(FairMindError, match="No such file"):
+        fm.run_monitoring("s", tmp_path / "missing.csv", attributes="g", score="s")
+
+
+def test_monitoring_inspect_and_attest(tmp_path):
+    csv = tmp_path / "d.csv"
+    csv.write_text("s,g\n0.4,a\n")
+    calls = []
+
+    def handler(request):
+        calls.append((request.method, request.url.path, request.headers.get("content-type", "")))
+        if request.url.path.endswith("/attestations"):
+            assert json.loads(request.content) == {"check": "monitoring", "statement": "Dashboards reviewed weekly", "reference": "RUN-1"}
+        return httpx.Response(200, json={})
+
+    fm = make(handler)
+    fm.run_monitoring("s", csv, attributes="g", score="s")
+    fm.inspect_csv("s", csv)
+    fm.attest("s", "monitoring", "Dashboards reviewed weekly", "RUN-1")
+    assert [(m, p.rsplit("/", 1)[-1]) for m, p, _ in calls] == [("POST", "monitoring-runs"), ("POST", "inspect"), ("POST", "attestations")]
+    assert all(c[2].startswith("multipart/") for c in calls[:2]) and calls[2][2] == "application/json"
+
+
+def test_org_id_from_env_or_first_organisation(monkeypatch):
+    calls = []
+
+    def handler(request):
+        calls.append(request.url.path)
+        return httpx.Response(200, json={"organizations": [{"id": "o1"}, {"id": "o2"}]})
+
+    monkeypatch.delenv("FAIRMIND_ORG_ID", raising=False)
+    fm = make(handler)
+    assert fm.organization_id() == "o1" and fm.organization_id() == "o1"
+    assert calls == ["/api/v1/organizations"]
+    monkeypatch.setenv("FAIRMIND_ORG_ID", "o9")
+    assert make(handler).organization_id() == "o9"
+
+
+def test_file_evaluation_uploads_slots_and_returns_run(tmp_path, monkeypatch):
+    monkeypatch.setenv("FAIRMIND_ORG_ID", "o1")
+    data = tmp_path / "train.csv"
+    data.write_text("a\n1\n")
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        seen["body"] = request.read()
+        return httpx.Response(200, json={"id": "ev1", "status": "passed"})
+
+    run = make(handler).run_evaluation("s1", "EV-DAT-01", {"train": data}, {"column": "a"})
+    assert run["status"] == "passed"
+    assert seen["url"] == "http://fm.test/api/v1/packs/evaluations/EV-DAT-01/runs?org_id=o1"
+    assert b'name="train"; filename="train.csv"' in seen["body"]
+    assert b'{"column": "a"}' in seen["body"] and b'name="mode"' not in seen["body"]
+
+
+def test_live_evaluation_waits_for_its_job(monkeypatch):
+    monkeypatch.setenv("FAIRMIND_ORG_ID", "o1")
+    polls = iter([{"id": "j1", "status": "running"}, {"id": "j1", "status": "done", "evidenceId": "ev7"}])
+
+    def handler(request):
+        path = request.url.path
+        if path.endswith("/runs"):
+            assert b"mode=live" in request.read()  # form-encoded when no files
+            return httpx.Response(202, json={"job": {"id": "j1", "status": "running"}})
+        if path.endswith("/evaluation-jobs/j1"):
+            return httpx.Response(200, json=next(polls))
+        assert path.endswith("/evaluation-runs/ev7")
+        return httpx.Response(200, json={"id": "ev7", "status": "failed"})
+
+    assert make(handler).run_evaluation("s1", "EV-SEC-01", live=True, poll_interval=0)["id"] == "ev7"
+
+
+def test_failed_job_and_missing_file_raise(tmp_path, monkeypatch):
+    monkeypatch.setenv("FAIRMIND_ORG_ID", "o1")
+
+    def handler(request):
+        if request.url.path.endswith("/runs"):
+            return httpx.Response(202, json={"job": {"id": "j1", "status": "failed", "error": "no judge"}})
+        raise AssertionError(request.url)
+
+    fm = make(handler)
+    with pytest.raises(FairMindError, match="no judge"):
+        fm.run_evaluation("s1", "EV-SEC-01", live=True)
+    with pytest.raises(FairMindError, match="No such file"):
+        fm.run_evaluation("s1", "EV-DAT-01", {"train": tmp_path / "missing.csv"})