Metadata-Version: 2.5
Name: cursive-blink
Version: 0.2.0
Summary: Customer SDK and CLI for Blink model deployments and evaluation campaigns
Author: Cursive
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.10
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.20; extra == 'mcp'
Description-Content-Type: text/markdown

# cursive-blink

The customer Python SDK and `blink` command-line tool for Blink. Upload supported
checkpoints, request model deployments, submit supported evaluation campaigns,
follow their progress, and download published results. You need a Blink service
URL and a customer team API key supplied by your Blink operator.

This package does not run a Blink server, schedule GPUs, execute evaluation
sandboxes, perform training or include model weights. Installation does not grant
access to a service, model or compute. Available features depend on the service's
configured capabilities and your team's permissions.

## Install

Linux and Python 3.12 or later are required. The initial release targets Linux
x86-64 and ARM64; macOS and Windows are not qualified. No CUDA, Torch or training
environment is required for the ordinary client.

For the CLI, install an isolated tool environment:

```sh
uv tool install --python 3.12 'cursive-blink==0.2.0'
blink --help
```

If your shell cannot find the command, run `uv tool update-shell` and start a new
shell. For Python integration, install into your project's environment instead:

```sh
uv add 'cursive-blink==0.2.0'
```

`uv tool install` does not expose the SDK to an unrelated Python environment.
For offline clusters, ask your operator for the matching wheel and a dependency
wheelhouse for the correct Python version and architecture.

## Configure and check access

Replace the example URL with the service URL supplied by your operator. This
command prompts for the customer API key without echoing it:

```sh
blink configure --base-url https://blink.example.com --output client.json
blink check --config client.json
```

For noninteractive setup, add `--key-file /private/blink/team-key.txt`; the file
must be owned by you and have `0600` permissions. Never put the key in
a command-line argument, a checked-in script or a chat message. Configuration and
transfer journals contain credentials and must remain private. The client checks
the key with the configured service before saving a new configuration.

`configure` authenticates an existing key; it does not sign you up, create a team
or bootstrap operator credentials. It will not overwrite an existing config.
`check` performs read-only authentication and capability checks and reports
separately whether campaign discovery is available. Run either command with
`--help` for all options.

## Common commands

In these examples, `client.json` is the private configuration produced by setup.
Replace uppercase placeholders with IDs/settings returned by your service.

```sh
blink capabilities --config client.json
blink upload --config client.json /absolute/checkpoint --request-key MY_UPLOAD_KEY
blink resume --config client.json job_RETURNED_JOB_ID
blink campaigns --config client.json recipes
blink campaigns --config client.json submit RECIPE_ID \
  --recipe-digest RECIPE_DIGEST --request-key MY_CAMPAIGN_KEY --model-id MODEL_ID
blink campaigns --config client.json watch cam_CAMPAIGN_ID
blink campaigns --config client.json artifacts cam_CAMPAIGN_ID
blink campaigns --config client.json download cam_CAMPAIGN_ID art_ARTIFACT_ID \
  --output /private/results/result.json
```

Uploaded checkpoint preparation/model registration follows the workflow exposed
by your selected deployment profile; an upload receipt alone is not a ready
model. `blink deploy`, `connect`, `heartbeat` and `stop` support customer-owned
harnesses. Use `blink COMMAND --help` for their required options.

Keep each request key stable when retrying the same submission. Uploads run in a
detached local worker and maintain durable resume journals: that machine still
needs to stay running until transfer completes. Exiting campaign `watch` does not
cancel the campaign. Use explicit cancellation, and distinguish accepted
cancellation from confirmed resource cleanup. Missing results or measurements
are not successful results or zero usage.

Supported task archives can be uploaded with `campaigns upload-task` and submitted
with `campaigns submit-tasks` only when the service enables a qualified runtime.
Upload acceptance is not execution approval. Team key replacement/revocation and
explicit retention previews are available through the same authenticated client;
revoking a management key does not cancel existing deployments or inference keys.

## Python SDK

```python
from cursive_blink import BlinkClient

client = BlinkClient.from_config("/private/blink/client.json")
print(client.capabilities())
print(client.campaigns())
```

The SDK supports checkpoint upload/resume, model/deployment management, campaign
submission/status/cancellation, scoped connection credentials and checksummed
artifact download. Optional `cursive_blink.harness.ManagedHarness` manages a
deployment lease and cleanup around your own harness; it does not supply or run
the harness. Its completion adapter currently returns non-streaming responses.

## Optional agent tools

```sh
uv tool install --python 3.12 'cursive-blink[mcp]==0.2.0'
blink mcp --config /private/blink/client.json
```

This starts a local stdio MCP server using the same customer credentials. MCP
exposes its own supported deployment-management tools; it is not a promise of
CLI/campaign feature parity. Run it where checkpoint files are readable. Core
CLI/SDK use does not need the MCP dependency.

## Compatibility and licence

Use the release recommended by your operator. Server-only updates do not require
automatic client upgrades; new client features still depend on server support.
This public package uses the `cursive_blink` Python namespace. Earlier private
monolithic builds used `blink`; migrate example imports accordingly. Do not
upgrade an existing Blink server environment using this customer distribution.

The included customer client is MIT licensed. This licence does not cover Blink's
private backend, third-party dependencies, customer data, credentials, model
weights or service access. Dependencies retain their own licences.
