Metadata-Version: 2.4
Name: blackant-sdk
Version: 1.1.95
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

The SDK includes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that allows AI agents (Claude Desktop, etc.) to interact with the BlackAnt platform through standardized tool calls.

### Installation

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

### Configuration

Set the following environment variables:

| Variable | Required | Description | Default |
|----------|----------|-------------|---------|
| `BLACKANT_USER` | Yes | Username for auto-authentication at startup | - |
| `BLACKANT_PASSWORD` | Yes | Password for auto-authentication at startup | - |
| `BLACKANT_BASE_URL` | No | BlackAnt platform URL | `https://dev.blackant.app` |
| `BLACKANT_LOG_LEVEL` | No | Logging level | `INFO` |

### Running the MCP Server

**Local (stdio) — for Claude Desktop, Cursor, VS Code:**
```bash
blackant-mcp --transport stdio
```

**Remote (SSE) — for Perplexity Computer, hosted deployment:**
```bash
blackant-mcp --transport sse --port 8000
```

| Variable | Description | Default |
|----------|-------------|---------|
| `BLACKANT_MCP_HOST` | SSE bind host | `0.0.0.0` |
| `BLACKANT_MCP_PORT` | SSE bind port | `8000` |
| `BLACKANT_MCP_AUTH` | Enable Keycloak token verification | `true` |

### Claude Desktop Configuration

Add to your `claude_desktop_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"
      }
    }
  }
}
```

### Perplexity Computer Configuration

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

| Field | Value |
|-------|-------|
| Name | BlackAnt Computing Platform |
| MCP Server URL | `https://dev.blackant.app/api/mcp/sse` |
| Transport | SSE |
| Auth | API Key (Keycloak Bearer token) |

### Docker Deployment

```bash
docker build -f src/blackant/mcp/Dockerfile -t blackant-mcp .
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
```

### Available MCP Tools

**Authentication:**

| Tool | Description |
|------|-------------|
| `blackant_authenticate` | Manual (re-)authentication with username/password |
| `blackant_token_status` | Check current authentication status |
| `blackant_test_connection` | Test connectivity to BlackAnt platform |

**Service Management:**

| Tool | Description |
|------|-------------|
| `blackant_build_service` | Build and deploy a Docker service |
| `blackant_list_services` | List all registered services |
| `blackant_get_service` | Get detailed service information |
| `blackant_service_status` | Get runtime status of a service |

**Scheduler (Computation):**

| Tool | Description |
|------|-------------|
| `blackant_create_schedule` | Create a computation schedule with parameters |
| `blackant_schedule_status` | Check schedule state (waiting/running/done/failed) |
| `blackant_get_task_result` | Get computation results and logs |
| `blackant_list_schedules` | List all schedules with states |
| `blackant_delete_schedule` | Delete a schedule (cleanup) |

### Example Agent Workflow

A researcher asks: *"Run my-calc with numbers [1,2,3,4,5] and show me the result"*

The agent calls the following tools in sequence:
1. `blackant_test_connection` — verify platform is reachable
2. `blackant_create_schedule(calculation_name="my-calc", cmd_args='{"numbers": [1,2,3,4,5]}')` — start computation
3. `blackant_schedule_status(schedule_uuid="...")` — poll until done
4. `blackant_get_task_result(schedule_uuid="...")` — retrieve results
5. `blackant_delete_schedule(schedule_uuid="...")` — cleanup

Any MCP-compatible agent (Claude Desktop, custom agents using the MCP SDK) can use these tools.

## 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
