ivcap_client 0.47.18

A client library for accessing an IVCAP cluster

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:

Concept	What it is
Service	A registered, executable analytic capability (Docker image + parameter schema)
Job	One invocation of a service — tracks lifecycle from pending → executing → succeeded
Artifact	A binary or structured data blob (image, CSV, model, …) stored in object storage
Aspect	A typed JSON assertion attached to any entity URN — forms the Datafabric knowledge graph
URN	The universal identifier for every platform entity (urn:ivcap:service:<uuid>, etc.)

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:

Mode	When to use	ENV vars
Platform (external)	Scripts, notebooks, and agents that access a live deployment	IVCAP_URL + IVCAP_JWT
Platform (in-container)	Service code running inside an IVCAP job container	IVCAP_BASE_URL (injected by platform)
Local	Developing and testing a service before deployment — no platform needed	(none)

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:

Script	What it demonstrates
list_services.py	List and inspect all available services
find_service_by_name.py	Look up a service by name
run_async_job.py	Async job submission and monitoring
upload_artifact.py	Upload a local file as an artifact
download_artifact.py	Download artifact content
list_artifacts.py	Browse artifacts in the platform
search_aspect.py	Query the Datafabric for aspects
run_crewai_agent.py	Run a CrewAI agent via IVCAP
batch_stress_test.py	Submit and monitor many parallel jobs
lambda_stress_test.py	Stress-test a Lambda-mode service

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

---

Going Deeper

AGENT.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 AGENT.md.

---

Related Projects

Project	Purpose
ivcap-core	The IVCAP platform itself
ivcap-service-sdk	Build and deploy services on IVCAP
ivcap-cli	Command-line tool (also the easiest way to get a JWT token)

---

License

See LICENSE.