blackant-sdk 1.1.96

Python SDK for Docker operations with automatic authentication through BlackAnt platform

BlackAnt SDK

Python SDK for Docker operations with automatic authentication through the BlackAnt platform.

Features

• Automatic authentication with BlackAnt platform
• Build Docker images on remote daemon
• Push images to private registry
• Service management (list, status, delete)
• Both Python API and CLI interface

Installation

pip install blackant-sdk

Quick Start

Python API

from blackant import BlackAntClient

# Initialize client
client = BlackAntClient(
    user="your-username",
    password="your-password",
    base_url="https://your-blackant-instance.com"
)

# Authenticate
if client.authenticate():
    print("Connected to BlackAnt!")

# Build and push a service
result = client.build_service(
    service_name="my-calculation",
    impl_path="./src/calculation/impl",
    tag="v1.0.0",
    push=True
)

print(f"Image: {result['full_image']}")

# List services
services = client.list_services()
for svc in services:
    print(f"  - {svc['name']}: {svc['status']}")

Command Line Interface (CLI)

# Set credentials via environment variables
export BLACKANT_USER=your-username
export BLACKANT_PASSWORD=your-password
export BLACKANT_URL=https://your-blackant-instance.com

# Test connection
blackant login

# Build and push
blackant build --name my-calculation --path ./src/calculation/impl --tag v1.0.0

# List services
blackant list

# Get service status
blackant status my-calculation

# Delete service
blackant delete my-calculation

Environment Variables

Variable	Description	Default
BLACKANT_USER	Username for authentication	-
BLACKANT_PASSWORD	Password for authentication	-
BLACKANT_URL	BlackAnt platform base URL	https://dev.blackant.app

API Reference

BlackAntClient

The main client class providing all SDK functionality.

Methods

Method	Description
authenticate()	Authenticate with BlackAnt platform
test_connection()	Test if connection is working
build_service(...)	Build Docker image and optionally push
list_services()	List all registered services
get_service(name)	Get service details
get_service_status(name)	Get service status
delete_service(name)	Delete a service

CLI Commands

Command	Description
blackant login	Test connection and authenticate
blackant build	Build Docker image and push to registry
blackant list	List all registered services
blackant status <name>	Get status of a service
blackant info <name>	Get detailed service information
blackant delete <name>	Delete a service

Use blackant <command> --help for detailed options.

MCP Interface — Use BlackAnt from AI Agents

The SDK includes a Model Context Protocol (MCP) server that exposes 12 tools to any MCP-compatible AI agent (Claude Desktop, Cursor, VS Code Continue, Perplexity Personal Computer, Perplexity Computer, custom agents). Researchers can then use the BlackAnt computing platform through natural language — no code, no CLI, no Python imports required.

Quick Start for AI Agents (3 steps, ~2 minutes)

Step 1 — Install the SDK with MCP extras

pip install "blackant-sdk[mcp]"

This installs the blackant-mcp command-line entry point alongside the regular SDK.

Step 2 — Verify the installation

blackant-mcp --help

You should see a help page listing --transport {stdio,sse}, --host, --port, and --no-auth options.

Step 3 — Register blackant-mcp as an MCP server in your AI agent

Pick the agent you use and follow the matching section below:

• Claude Desktop — macOS, Windows, Linux
• Cursor — stdio local
• VS Code + Continue — stdio local
• Perplexity Personal Computer — Mac Mini, local stdio
• Perplexity Computer (Pro/Max) — cloud, remote SSE
• MCP Inspector — for testing and development

Once registered, ask the agent in plain language:

"List all services on BlackAnt" "Run the oe-demo calculation with numbers [1, 2, 3, 4, 5] and show me the result" "Check the status of the wave-simulation service"

The agent will pick the right tools and chain them automatically.

---

Environment Variables

The blackant-mcp server is configured via environment variables. Set them in the env block of your agent's MCP config (preferred) or export them in your shell.

Variable	Required	Description	Default
BLACKANT_USER	Yes (stdio)	Username for platform authentication	—
BLACKANT_PASSWORD	Yes (stdio)	Password for platform authentication	—
BLACKANT_BASE_URL	No	BlackAnt platform URL	https://dev.blackant.app
BLACKANT_LOG_LEVEL	No	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO
BLACKANT_MCP_HOST	No	SSE bind host (SSE transport only)	0.0.0.0
BLACKANT_MCP_PORT	No	SSE bind port (SSE transport only)	8000
BLACKANT_MCP_AUTH	No	Enable Keycloak token verification for SSE	true
BLACKANT_JWT_PUBLIC_KEY	No	Keycloak public key for local JWT signature verification (production SSE)	—
BLACKANT_JWT_ALGORITHM	No	JWT signing algorithm	RS256
BLACKANT_JWT_ISSUER	No	Expected JWT issuer claim	—

---

Claude Desktop

Claude Desktop runs blackant-mcp locally via stdio transport.

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add this to the file (create it if missing):

{
  "mcpServers": {
    "blackant": {
      "command": "blackant-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "BLACKANT_USER": "your-username",
        "BLACKANT_PASSWORD": "your-password",
        "BLACKANT_BASE_URL": "https://dev.blackant.app"
      }
    }
  }
}

Then quit and restart Claude Desktop. In a new chat, type "List all services on BlackAnt" — Claude will discover the 12 tools automatically and pick the right one.

Note: If blackant-mcp is not on Claude Desktop's PATH, use the absolute path from which blackant-mcp as the command value (typical: /usr/local/bin/blackant-mcp or /home/<you>/.local/bin/blackant-mcp).

---

Cursor and VS Code + Continue

Cursor: Settings → MCP → Add new MCP Server. Paste:

{
  "mcpServers": {
    "blackant": {
      "command": "blackant-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "BLACKANT_USER": "your-username",
        "BLACKANT_PASSWORD": "your-password",
        "BLACKANT_BASE_URL": "https://dev.blackant.app"
      }
    }
  }
}

VS Code + Continue: edit ~/.continue/config.json and add the same mcpServers block.

Reload the IDE. You can now @-mention the BlackAnt tools in chat: "@blackant list all running services".

---

Perplexity Personal Computer

Perplexity Personal Computer (Mac Mini) runs local MCP servers via the PerplexityXPC helper. Setup is identical to Claude Desktop:

Config file: ~/Library/Application Support/Perplexity/mcp_config.json

{
  "mcpServers": {
    "blackant": {
      "command": "blackant-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "BLACKANT_USER": "your-username",
        "BLACKANT_PASSWORD": "your-password",
        "BLACKANT_BASE_URL": "https://dev.blackant.app"
      }
    }
  }
}

If Perplexity has a UI for adding connectors (Settings → Connectors → + Local), use that instead — the fields map 1:1 to the JSON above.

Restart Perplexity after editing the config.

---

Perplexity Computer (Pro/Max)

Perplexity Computer (the cloud product, requires Pro or Max subscription) uses remote MCP servers via SSE over HTTPS. You need the BlackAnt MCP server hosted at a public HTTPS endpoint.

For local testing, expose the SSE server with an ngrok tunnel:

# Terminal 1 — start MCP in SSE mode (disable auth for local testing only)
BLACKANT_USER=your-username \
BLACKANT_PASSWORD=your-password \
BLACKANT_BASE_URL=https://dev.blackant.app \
BLACKANT_MCP_AUTH=false \
blackant-mcp --transport sse --port 8000

# Terminal 2 — public HTTPS tunnel (requires an ngrok account)
ngrok http 8000
# Copy the https://<random>.ngrok-free.dev URL

For production, deploy the server on the BlackAnt infrastructure (see Docker Deployment) and expose it via nginx at e.g. https://dev.blackant.app/api/mcp/sse.

In Perplexity: Settings → Connectors → + Custom connector → Remote:

Field	Value
Name	BlackAnt Computing Platform
MCP Server URL	https://<ngrok-url>/sse (or https://dev.blackant.app/api/mcp/sse)
Transport	SSE
Auth	API Key — paste a Keycloak Bearer token (obtained via POST /api/auth/login)

Click Add, then open a new Computer task and try: "List all BlackAnt services".

---

MCP Inspector (for testing and development)

The MCP Inspector is a browser-based debugging UI that lets you invoke each tool manually without an AI agent. Useful for validating the server before wiring it into a real agent.

BLACKANT_USER=your-username \
BLACKANT_PASSWORD=your-password \
BLACKANT_BASE_URL=https://dev.blackant.app \
npx @modelcontextprotocol/inspector blackant-mcp --transport stdio

The Inspector prints a URL like http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=…. Open it in your browser, click Tools in the left sidebar, select a tool, fill in parameters, and hit Run Tool.

To test the SSE transport, start blackant-mcp --transport sse --port 8000 first, then in the Inspector switch Transport Type to SSE and enter http://localhost:8000/sse.

---

Docker Deployment

To run the MCP server as a hosted service on BlackAnt infrastructure (Docker Swarm):

# Build the image from the bundled Dockerfile
docker build -f src/blackant/mcp/Dockerfile -t blackant-mcp:latest .

# Run as a local container
docker run -p 8000:8000 \
  -e BLACKANT_USER=your-username \
  -e BLACKANT_PASSWORD=your-password \
  -e BLACKANT_BASE_URL=https://dev.blackant.app \
  blackant-mcp:latest

# Or deploy to Swarm
docker service create \
  --name blackant-mcp \
  --network science_module_callback_net \
  --publish 8000:8000 \
  --env BLACKANT_USER=admin \
  --env BLACKANT_PASSWORD=... \
  --env BLACKANT_BASE_URL=https://dev.blackant.app \
  blackant-mcp:latest

Then add an nginx rule to proxy /api/mcp/sse to blackant-mcp:8000/sse:

location /api/mcp/ {
    proxy_pass http://blackant-mcp:8000/;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 24h;
}

---

Available MCP Tools (12 total)

Each tool is callable from any MCP client. Parameters and return shapes are documented in the in-process JSON schema (visible via tools/list in the MCP protocol).

Authentication & Diagnostics

Tool	Parameters	Description
blackant_authenticate	username, password	Authenticate with BlackAnt. Rejected in SSE mode (server uses startup credentials). Never returns the raw token.
blackant_token_status	—	Return {authenticated: bool, username: str} for the current session.
blackant_test_connection	—	Probe the BlackAnt platform and Service Registry. Returns {connected: bool, message: str}.

Service Management

Tool	Parameters	Description
blackant_build_service	source_path, service_name, gpu_count=0, description=""	Build a Docker image from source_path, push it to the private registry, and register the service. Requires a Dockerfile in source_path. GPU count must be 0–8.
blackant_list_services	namespace="default"	List all registered services with name, ID, image, and state.
blackant_get_service	service_name	Detailed metadata: image tag, registration date, labels, configuration.
blackant_service_status	service_name	Runtime status: replicas, node placement, last health check.

Scheduler (Computation Workflow)

Tool	Parameters	Description
blackant_create_schedule	calculation_name, image_tag="latest", cmd_args=""	Submit a computation. cmd_args is a JSON string, e.g. '{"numbers": [1,2,3]}'. Returns schedule_uuid.
blackant_schedule_status	schedule_uuid	Current state: waitingForTrigger, running, done, permanentFailure. Also returns is_terminal for polling.
blackant_get_task_result	schedule_uuid	Task results with parsed output, execution time, and logs (first 1000 chars).
blackant_list_schedules	—	Summary of all schedules with UUID, calculation name, state, and creation time.
blackant_delete_schedule	schedule_uuid	Remove a schedule. Use for cleanup after retrieving results.

---

Example Agent Workflows

Workflow 1 — Run a Calculation End-to-End

Researcher asks:

"Run the oe-demo calculation with numbers [1, 2, 3, 4, 5] and tell me the sum."

Agent's tool calls (automatic, in sequence):

1. blackant_test_connection() → {connected: true}
2. blackant_create_schedule(calculation_name="oe-demo", image_tag="latest", cmd_args='{"numbers":[1,2,3,4,5]}') → {schedule_uuid: "abc-123"}
3. blackant_schedule_status(schedule_uuid="abc-123") → poll until state="done"
4. blackant_get_task_result(schedule_uuid="abc-123") → parsed result, e.g. {"sum": 15, "count": 5, "average": 3.0}
5. blackant_delete_schedule(schedule_uuid="abc-123") → cleanup

Agent replies: "The sum is 15. The calculation took 13 seconds and processed 5 numbers."

Workflow 2 — Deploy a New Calculation

Researcher asks:

"Build my calculation from ~/projects/wave-sim with 2 GPUs."

Agent's tool calls:

1. blackant_test_connection()
2. blackant_build_service(source_path="/home/researcher/projects/wave-sim", service_name="wave-sim", gpu_count=2) → {service_id: "...", status: "BUILD_SUCCESS"}
3. blackant_service_status(service_name="wave-sim") → confirm deployment

Workflow 3 — Monitor Running Work

Researcher asks:

"What's still running on BlackAnt?"

Agent's tool calls:

1. blackant_list_schedules() → filter state="running" → summary
2. (Optional) blackant_schedule_status(...) for each to get details

---

Troubleshooting

Symptom	Cause	Fix
blackant-mcp: command not found after pip install	Shell hasn't picked up the new entry point	Open a new terminal, or ensure $HOME/.local/bin is on PATH
Agent says "No tools available"	Agent config is pointing to the wrong command	Run which blackant-mcp and put the absolute path in the MCP config
Authentication failed: 401 at startup	Wrong username/password or expired account	Test with curl -X POST https://dev.blackant.app/api/auth/login -d "username=X&password=Y"
Not authenticated when calling tools	Missing BLACKANT_USER/BLACKANT_PASSWORD env vars	Set them in the env block of your agent's MCP config
Tokens expire during long sessions	Keycloak token TTL is 60 s	Handled automatically — the session refreshes before each tool call (50 s threshold)
SSE connection drops through Perplexity	Proxy/tunnel buffers SSE responses	Disable buffering: proxy_buffering off in nginx, or use --host-header flags in ngrok
Forged-JWT bypass warning	—	All tokens are verified server-side via Keycloak introspection; unsigned JWTs are rejected

Requirements

• Python 3.11+
• Access to a BlackAnt platform instance
• Valid BlackAnt credentials

License

Proprietary - Obuda University, John von Neumann Faculty of Informatics

---

About

This SDK is developed and maintained by the BlackAnt Development Team at:

Obuda University - John von Neumann Faculty of Informatics (Óbudai Egyetem - Neumann János Informatikai Kar)

Address	1034 Budapest, Bécsi út 96/B, Hungary
Phone	[phone]
Email	[e-mail]
Web	nik.uni-obuda.hu

Support

For SDK issues and questions, contact the BlackAnt Development Team at [e-mail]