Mankinds SDK

Choose your language:

The SDK lets application code declare an AI system, configure its target connection, prepare datasets and test plans, run evaluations, trigger agents, manage agent gates, then read evidence, findings and remediation items.

It does not expose Mankinds administration routes, webapp internals, OAuth flows, Copilot, ontology internals, users, roles or organization settings.

Install

pip install mankinds-sdk>=2.0.0

Authentication

Create an API key in Mankinds, store it as MANKINDS_API_KEY, and initialize the client with that key. The organization is derived from the key; do not send an organization id in SDK calls.

Use SDK access for the SDK examples below. CI access is intended for pipeline runners that only trigger an agent run and read its result.

SDK Quickstart

Initialize

import os
from mankinds_sdk import MankindsClient

client = MankindsClient(api_key=os.environ["MANKINDS_API_KEY"])

Create a system and connection

system = client.systems.create({
  "name": "Support Assistant",
  "description": "Customer support assistant for billing and account questions.",
})

connection = client.connections.create(
  system["id"],
  {
      "connector_type": "custom_api",
      "url": "https://api.example.com/chat",
      "method": "POST",
      "body": {"message": "{{input}}"},
      "input_path": "message",
      "output_path": "reply",
  },
  name="Pre-production API",
  is_default=True,
)

Generate or import a dataset

Long operations return a job. Poll through client.jobs.wait(...).

job = client.datasets.generate(system["id"], {"scenarioCount": 20})
dataset = client.jobs.wait(job["id"])

client.datasets.validate(system["id"])

Run an evaluation

Evaluation start is asynchronous. Waiting is explicit.

run = client.evaluations.run({
  "systemId": system["id"],
  "profile": "required",
  "connectionId": connection["id"],
})

evaluation = client.evaluations.wait(run["evaluation_id"])
print(evaluation.get("summary", {}).get("overall_score"))

What to Read Next

Page	Use it for
Systems	Create, read, update and archive AI systems.
Connections	Configure and validate target endpoints.
Datasets	Generate, import, update and validate evaluation scenarios.
Test plans	Generate and read system test plans.
Evaluations	Run, list, read, cancel and wait for evaluations.
Agents and Gates	Trigger existing agents and manage gate configuration.
Evidence, Findings, Remediation	Read outputs produced by Mankinds.

Namespaces

Namespace	Purpose
client.whoami()	Inspect the authenticated organization and actor.
client.systems	Create, list, get, update and delete AI systems.
client.connections	Create target connections, test them and set defaults.
client.datasets	Generate, import, get, update and validate datasets. Python uses import_.
client.testPlans / client.test_plans	Generate and read system test plans.
client.evaluations	Run, list, get, cancel and explicitly wait for evaluations.
client.jobs	Poll asynchronous jobs.
client.agents	List agents, trigger agent runs, inspect runs and wait for gate-aware completion.
client.gates	Read and update the gate configuration attached to an agent.
client.evidence	Retrieve machine-readable evidence packs.
client.findings	List evaluation findings.
client.remediation	List remediation items.

Async Model

Dataset generation, test-plan generation and other long operations return a JobRef.

job = client.test_plans.generate(
  system["id"],
  {"nbTests": 5},
)
result = client.jobs.wait(job["id"], timeout_ms=15 * 60 * 1000, interval_ms=5000)