Cresco Python Client (pycrescolib)

Python client library for the Cresco edge-computing framework. It connects to the wsapi WebSocket plugin (wss://host:8282, authenticated with the cresco_service_key header) to control agents, deploy plugins, run pipelines, stream the data plane, and build stunnel tunnels.

Part of the Cresco framework — see the agent repository for the full architecture and the Java client for the equivalent in Java.

Standardized clients. The Python and Java clients are kept feature- and name-identical: the same submodules (messaging, agents, admin, api, globalcontroller, stunnel), the same method names (snake_case in both languages), the same behavior, and the same examples. Anything you can do in one, you can do in the other with the same call. This README is identical to the Java client's, except for the install and quick-start sections below.

Install: pip install pycrescolib (Python 3.8+; depends on websockets, cryptography, backoff). From a source checkout use pip install ., and to build the distributions run python -m build.

Quick start

from pycrescolib.clientlib import clientlib

# host/ip of an agent running the wsapi plugin, its port, and the wsapi service key
client = clientlib("localhost", 8282, "your-service-key", verify_ssl=False)

if client.connect():
    print(client.api.get_api_region_name(), client.api.get_api_agent_name())
    print(client.globalcontroller.get_agent_list())
    client.close()

Runnable, standardized examples (identical to the Java client's example/standard/StandardExamples.java) live in examples/standard_examples.py: example_connect, example_pipeline, example_plugin_lifecycle, example_dataplane, example_logstreamer, example_admin.

Concepts

• Connect once, use submodules. A clientlib opens one authenticated control connection and exposes six submodule handles: messaging, agents, admin, api, globalcontroller, stunnel.
• Resolve plugins by name, not by log-scraping. globalcontroller.find_plugin(region, agent, name) returns the live plugin_id for a plugin loaded on an agent, so you never parse logs to address a plugin.
• Streams are separate sockets. get_dataplane(...) and get_logstreamer(...) open their own WebSocket connections, are tracked by name on the client, and auto-reconnect if the socket drops.
• RPC vs fire-and-forget. Messaging calls take an is_rpc flag: when true the call blocks for the reply, when false it is sent without waiting.

API reference

Signatures are shown language-neutrally; names and behavior are identical in both clients.

Client — clientlib / CrescoClient

Submodule handles: messaging, agents, admin, api, globalcontroller, stunnel.

api

admin

agents

globalcontroller

The metric/capability inventories take scope = 'node', 'region', or 'global'; pass dst_region+dst_agent to target one agent's controller. (In the Java client these two methods currently order the positional args as dst_region, dst_agent, scope, ….)

stunnel

Build and manage secure TCP tunnels through the io.cresco.stunnel plugin: a listener on src_port at the source agent forwards to dst_host:dst_port reachable from the destination agent, with tunnel data riding the Cresco data plane. Plugin ids are auto-resolved by name via find_plugin, so callers never pass a raw plugin_id.

messaging

All take (is_rpc, message_event_type, message_payload, ...) and return the reply dict for RPC calls.

dataplane (from get_dataplane)

logstreamer (from get_logstreamer)

SSL verification

By default SSL certificate verification is disabled (Cresco agents use self-signed certs). Enable it with the constructor flag:

client = clientlib("localhost", 8282, "your-service-key", verify_ssl=True)

Testing & cross-language parity

Both clients ship a self-contained test suite (no live mesh needed) that asserts they emit identical wire messages for identical API calls — the Python and Java suites assert the same generated golden corpus, so a green run on both proves the clients produce the same results.

• Python: pip install -e .[test] && pytest
• Java: mvn test

See the test-suite README for coverage, the canonical wire contract, and how to regenerate the golden corpus after adding or changing a method.

License

See LICENSE.txt.