ivcap-client — Python SDK for IVCAP

ivcap-client is a Python library for interacting with an IVCAP (Intelligent Visual Computing and Analytics Platform) deployment from the outside — from your laptop, a notebook, a data pipeline, or an AI agent.

Use it to:

• Discover and invoke services — find registered analytic capabilities by name or URN and submit jobs to them
• Monitor jobs — poll status and retrieve results as jobs move through the platform
• Manage artifacts — upload data files and download results (images, CSV, NetCDF, …)
• Work with the Datafabric — read and write typed metadata (Aspects) attached to any platform entity; query provenance across the emergent knowledge graph
• Orchestrate workflows — chain service calls, fan out parallel jobs, and integrate IVCAP into broader data pipelines or agentic systems

Want to build and deploy your own analytic service on IVCAP? Use the ivcap-service-sdk instead. Packaging your code as an IVCAP service lets it take full advantage of the platform's managed compute and storage, and makes it a reusable, discoverable building block that other users and agents can invoke through the same API described here.

Contents

• Installation
• Quick Start
• Core Concepts
• Common Patterns
• Local Mode — Testing Services Without a Platform
• Examples
• Going Deeper
• Related Projects

Installation

pip install ivcap-client

Quick Start

from ivcap_client.ivcap import IVCAP

# Reads IVCAP_URL and IVCAP_JWT from environment variables (or a .env file)
ivcap = IVCAP()

# List available services
for service in ivcap.list_services(limit=10):
    print(service)

# Find a service by name and run a job
# request_job accepts a Pydantic BaseModel, dataclass, or IO[str] (JSON)
import io, json
service = ivcap.get_service_by_name("hello-world-python")
job = service.request_job(io.StringIO(json.dumps({"msg": "Hello, IVCAP!"})))

# Wait for the result
while not job.finished:
    import time; time.sleep(5)
    job.refresh()

print(job.result)

Credentials

You need an IVCAP deployment URL and a JWT access token. The easiest way to get a token is via the ivcap-cli:

ivcap context get access-token

Set your credentials as environment variables or in a .env file:

IVCAP_URL=https://api.your-ivcap-deployment.net
IVCAP_JWT=<your-jwt-token>
IVCAP_ACCOUNT_ID=urn:ivcap:account:<uuid>   # optional

Core Concepts

IVCAP is built around five first-class concepts:

The platform supports multiple execution backends (Lambda, Batch, Nextflow, Argo) — you don't need to know which one a service uses; the request_job() call is the same for all of them.

Common Patterns

Upload data, run a service, download the result

from ivcap_client.ivcap import IVCAP

ivcap = IVCAP()

# Upload an input artifact
artifact = ivcap.upload_artifact(name="input-image", file_path="/data/photo.jpg")

# Find the service and submit a job
import io, json
service = ivcap.get_service_by_name("my-image-processor")
job = service.request_job(io.StringIO(json.dumps({"image": artifact.id, "threshold": 0.8})))

# Poll until done
import time
while not job.finished:
    time.sleep(5)
    job.refresh()

# Download the output artifact
output = ivcap.get_artifact(job.result["output_artifact"])
with output.as_local_file() as path:
    print(f"Result saved at: {path}")

Attach metadata to any entity

ivcap.add_aspect(
    entity="urn:ivcap:artifact:<uuid>",
    aspect={
        "$schema": "urn:my-project:schema:image-annotation.1",
        "label": "coral reef",
        "confidence": 0.97,
    },
)

Async usage

All major operations have _async variants for use with asyncio:

import asyncio
from ivcap_client.ivcap import IVCAP

async def run():
    ivcap = IVCAP()
    svc = ivcap.get_service("urn:ivcap:service:<uuid>")
    Model = await svc.request_model_async()
    job = await svc.request_job_async(Model(param="value"))
    result = await job.result_async()
    print(result)

asyncio.run(run())

Local Mode — Testing Services Without a Platform

ivcap-client supports three operating modes, all selected automatically from environment variables with the same ivcap = IVCAP() call:

When neither IVCAP_URL nor IVCAP_BASE_URL is set, IVCAP() automatically returns a LocalIVCAP instance — a filesystem-backed subclass that stores artifacts and aspects on disk. This is the recommended way to test a service locally before deploying it:

from ivcap_client import IVCAP

ivcap = IVCAP()   # → LocalIVCAP when no IVCAP_URL is set

artifact = ivcap.upload_artifact(name="result.csv", file_path="/tmp/result.csv")
print(artifact.id)
# urn:file:///abs/path/to/ivcap-artifacts/artifacts/result.csv

ivcap.add_aspect(
    entity=artifact.id,
    aspect={"$schema": "urn:my:schema:result.1", "rows": 42},
)

Artifacts land in ivcap-artifacts/artifacts/ and aspects in ivcap-artifacts/aspects/ (configurable via IVCAP_LOCAL_DIR or the base_dir argument to IVCAP.local()).

For the full picture — mode detection logic, unit-test patterns, and the LocalIVCAP capability table — see the Local Mode guide.

Examples

The examples/ directory contains ready-to-run scripts covering the most common use cases:

All examples read credentials from a .env file (or environment variables). See examples/_common.py for the shared setup logic.

Going Deeper

AGENTS.md is a comprehensive reference guide — written primarily for AI agents, but equally useful for developers who want the full picture. It covers:

• A detailed explanation of every platform concept (Services, Jobs, Artifacts, Aspects, URNs, the Datafabric)
• The complete end-to-end request lifecycle
• Full API reference with parameter tables for every operation
• Async patterns and parallel job management
• Error handling and all exception types
• Environment variable reference

If you want to understand why the API works the way it does, or need exhaustive parameter documentation, start with AGENTS.md.

Related Projects

License

See LICENSE.