Metadata-Version: 2.4
Name: blackant-sdk
Version: 1.1.96
Summary: Python SDK for Docker operations with automatic authentication through BlackAnt platform
Author-email: Balázs Milán <milan.balazs@uni-obuda.hu>
Maintainer-email: BlackAnt Development Team <dev@blackant.app>
License: Proprietary - Óbudai Egyetem
Project-URL: Homepage, https://env.blackant.app/systemdevelopers/blackant_sdk
Project-URL: Documentation, https://docs.blackant.app
Project-URL: Repository, https://env.blackant.app/systemdevelopers/blackant_sdk
Project-URL: Bug Tracker, https://env.blackant.app/systemdevelopers/blackant_sdk/-/issues
Keywords: docker,sdk,authentication,blackant,container,orchestration,swarm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: flask>=2.3.2
Requires-Dist: flask-restful>=0.3.10
Requires-Dist: waitress>=2.1.2
Requires-Dist: minio>=6.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: docker>=4.4.3
Requires-Dist: urllib3<2.0
Requires-Dist: gunicorn>=21.2.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: python-keycloak>=3.0.0
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: click>=8.1.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: sphinx>=5.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
Requires-Dist: mcp>=1.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: mcp>=1.0.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"

# 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

```bash
pip install blackant-sdk
```

## Quick Start

### Python API

```python
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)

```bash
# 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](https://modelcontextprotocol.io) (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**

```bash
pip install "blackant-sdk[mcp]"
```

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

**Step 2 — Verify the installation**

```bash
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](#claude-desktop) — macOS, Windows, Linux
- [Cursor](#cursor-and-vs-code-continue) — stdio local
- [VS Code + Continue](#cursor-and-vs-code-continue) — stdio local
- [Perplexity Personal Computer](#perplexity-personal-computer) — Mac Mini, local stdio
- [Perplexity Computer (Pro/Max)](#perplexity-computer-promax) — cloud, remote SSE
- [MCP Inspector](#mcp-inspector-for-testing-and-development) — 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):**

```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"
      }
    }
  }
}
```

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:

```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"
      }
    }
  }
}
```

**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`

```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:

```bash
# 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](#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](https://github.com/modelcontextprotocol/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.

```bash
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):

```bash
# 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`:

```nginx
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

<p align="center">
  <img src="https://nik.uni-obuda.hu/wp-content/uploads/2025/10/NIK_logo_header.png" alt="NIK Logo" width="300"/>
</p>

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 | +36 1 666 5520 |
| Email | titkarsag@nik.uni-obuda.hu |
| Web | [nik.uni-obuda.hu](https://nik.uni-obuda.hu) |

## Support

For SDK issues and questions, contact the BlackAnt Development Team at dev@blackant.app
