CrucibleClient

The main entry point for the nano-crucible Python API. Instantiating CrucibleClient loads credentials from config or environment variables and initializes all resource namespaces.

from crucible import CrucibleClient

client = CrucibleClient()
# or with explicit credentials:
client = CrucibleClient(api_url="https://crucible.lbl.gov/api/v2", api_key="your-key")

Resource namespaces

Attribute	Type	Description
client.datasets	DatasetOperations	Dataset CRUD, file upload, metadata, ingestion
client.samples	SampleOperations	Sample CRUD, hierarchies, dataset links
client.projects	ProjectOperations	Project CRUD, user management
client.instruments	InstrumentOperations	Instrument CRUD
client.users	UserOperations	User management (admin)
client.graphs	GraphOperations	Entity graph traversal
client.deletions	DeletionOperations	Deletion request management

Reference

crucible.client.CrucibleClient

__init__(api_url=None, api_key=None)

Initialize the Crucible API client.

Parameters:

Name	Type	Description	Default
api_url	Optional[str]	Base URL for the Crucible API (loads from config if not provided)	None
api_key	Optional[str]	API key for authentication (loads from config if not provided)	None

Raises:

Type	Description
ValueError	If api_url or api_key not provided and not found in config

health()

Check API and database health without requiring authentication.

Returns:

Name	Type	Description
Dict	Dict	{"status": "ok"|"degraded", "db": "ok"|"error", "db_ms": float|None, "version": str|None} Raises requests.exceptions.ConnectionError if the host is unreachable.

whoami()

Return account info for the current API key.

Returns:

Name	Type	Description
Dict	Dict	user_unique_id, access_group_ids, and user_info with full user profile fields.

get(resource_id, resource_type=None, include_metadata=False, include_links=False)

Get a resource by ID with automatic type detection.

Parameters:

Name	Type	Description	Default
resource_id	str	The unique identifier (mfid) of the resource	required
resource_type	str	Resource type ('sample', 'dataset', 'instrument'). If not provided, will be auto-detected.	None
include_metadata	bool	Include scientific metadata	False
include_links	bool	Include immediate parent/child/associated links	False

Returns:

Name	Type	Description
Dict	Dict	Resource data

Raises:

Type	Description
ValueError	If resource type is unknown or not supported

get_resource_type(resource_id)

Determine the type of a resource.

Parameters:

Name	Type	Description	Default
resource_id	str	The unique identifier (mfid) of the resource	required

Returns:

Name	Type	Description
str	str	resource_type

get_links(resource_id)

Return immediate links for any resource (dataset or sample).

Hits GET /resources/{id}/links and returns a flat list of link dicts: [{"unique_id": "...", "resource_type": "dataset|sample", "name": "...", "relationship": "parent|child|associated"}, ...]

Parameters:

Name	Type	Description	Default
resource_id	str	Dataset or sample unique identifier	required

Returns:

Name	Type	Description
list	list	Link objects, or empty list if none

link(parent_id, child_id)

Link two resources with automatic type detection.

Automatically determines resource types and creates appropriate link: - Both datasets: Creates parent-child dataset relationship - Both samples: Creates parent-child sample relationship - Dataset + sample: Links sample to dataset

Parameters:

Name	Type	Description	Default
parent_id	str	Parent resource unique identifier	required
child_id	str	Child resource unique identifier	required

Returns:

Name	Type	Description
Dict	Dict	Information about the created link

Raises:

Type	Description
ValueError	If resource types cannot be determined or combination is invalid

Example

Link two datasets

client.link('parent_dataset_id', 'child_dataset_id')

Link two samples

client.link('parent_sample_id', 'child_sample_id')

Link sample to dataset

client.link('dataset_id', 'sample_id')

unlink(id_a, id_b)

Unlink two resources with automatic type detection.

Automatically determines resource types and removes the appropriate link: - Both datasets: Removes parent-child dataset relationship - Both samples: Removes parent-child sample relationship - Dataset + sample: Removes dataset-sample link

Parameters:

Name	Type	Description	Default
id_a	str	First resource unique identifier (dataset or sample)	required
id_b	str	Second resource unique identifier (dataset or sample)	required

Returns:

Name	Type	Description
Dict	Dict	Deletion confirmation

Raises:

Type	Description
ValueError	If resource types cannot be determined or combination is invalid.

download(resource_id, output_dir='crucible-downloads', no_files=False, no_record=False, overwrite_existing=True, include=None, exclude=None)

Download a resource record and, for datasets, its files.

Parameters:

Name	Type	Description	Default
resource_id	str	Sample or dataset unique identifier	required
output_dir	str	Directory to save files (default: 'crucible-downloads')	'crucible-downloads'
no_files	bool	Skip file download, save record JSON only	False
no_record	bool	Skip saving record.json	False
overwrite_existing	bool	Overwrite existing files (default: True)	True
include	list	Glob patterns — only download matching files	None
exclude	list	Glob patterns — skip matching files	None

Returns:

Type	Description
List[str]	List[str]: Paths of all downloaded files (record.json + data files)