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_key="your-key")
A new client uses the first credential it finds: an api_key argument, then CRUCIBLE_API_KEY, then the sign-in stored by crucible login or client.login(), then api_key in the config file. client.credential_source reports which one is in use. client.login() signs in with a browser (method="device" approves a code on any device, for SSH or headless machines; method="paste" asks for the code the sign-in page shows, for when the browser cannot reach the program) and switches the client to that session; client.logout() ends and forgets the stored sign-in.
Resource namespaces¶
| Attribute | Type | Description |
|---|---|---|
client.datasets |
DatasetOperations |
Dataset CRUD, file upload/download, thumbnails, metadata |
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.files |
FileOperations |
File lookup, download, and ingestion by MFID |
client.account |
AccountOperations |
Self-service profile, API keys, verification |
client.ingestions |
IngestionOperations |
Ingestion request management |
client.postprocessing |
PostprocessingOperations |
Postprocessing pipelines and runs |
client.graphs |
GraphOperations |
Entity graph traversal |
client.deletions |
DeletionOperations |
Deletion request management |
client.access_groups |
AccessGroupOperations |
Project join requests |
client.service_accounts |
ServiceAccountOperations |
Service-account creation, key rotation, and administration |
client.print |
PrintOperations |
Label-printer jobs |
Privilege mode¶
Endpoints distinguish normal ACL-derived authorization from explicit platform-administrator elevation, selected with the Crucible-Privilege-Mode header. By default the client sends no header and the server decides: a platform administrator using an API key runs elevated and sees every record, a signed-in administrator runs normal, and everyone else gets their normal, ACL-derived access. client.is_elevated reports the mode the server applies.
Pass privilege_mode="normal" to see only what you can access through your own memberships and grants, or "elevated" to request elevation explicitly. The privilege_mode config key and CRUCIBLE_PRIVILEGE_MODE environment variable set the same thing.
A future release will default to normal for API keys too. Platform administrators whose scripts rely on seeing every record should set privilege_mode = elevated now.
Administrator-only operations, such as service-account administration and deletion review, request elevation per call, so they work without elevating the whole client. Requesting elevation as an ineligible caller is rejected with a 403, so those calls elevate only when client.can_elevate is true.
Authorization and capabilities¶
client.authorization (an AccountAuthorization) and client.capabilities (an AccountCapabilities) expose the caller's platform role and account-level permissions. They are read once from /account/profile and cached; call client.refresh_profile() to re-read them, for example after changing privilege_mode or after an administrator changes your role.
A flag the profile did not report is None, so check for an explicit False before refusing; otherwise attempt the operation and let the API decide.
Reference¶
crucible.client.CrucibleClient
¶
credential_source
property
¶
What this client authenticates with: 'argument', 'CRUCIBLE_API_KEY', 'config file' (API keys), 'sign-in' (stored by login), or 'this session'.
authorization
property
¶
The caller's platform_role and whether they can elevate.
Fetched once from /account/profile and cached; call refresh_profile() to re-read it. An unreadable profile yields empty values, so callers degrade to "no extra authority" rather than failing.
capabilities
property
¶
The caller's account-level capability flags, cached like authorization.
They describe the authority of the privilege mode the client was in when the profile was read; call refresh_profile() after changing privilege_mode.
can_elevate
property
¶
Whether this caller may request elevated privilege mode at all.
is_elevated
property
¶
Whether ordinary requests from this client run elevated.
Without an explicit mode the server decides: it elevates an administrator's API key but not a sign-in, and reports which.
__init__(api_url=None, api_key=None, privilege_mode=None)
¶
Initialize the Crucible API client.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
api_url
|
Optional[str]
|
Base URL for the Crucible API (loads from config or the package default if not provided) |
None
|
api_key
|
Optional[str]
|
API key for authentication (loads from config if not provided) |
None
|
privilege_mode
|
Optional[str]
|
"normal" or "elevated". Sent as the Crucible-Privilege-Mode header on every request. Elevated mode is what lets a platform administrator see beyond their own ACL-derived access. Loads from config if not provided. When unset, no header is sent and the server applies its legacy behavior: elevated for a platform administrator, normal for everyone else. Admin-only operations request elevation per call regardless of this setting. |
None
|
Without api_key, the client uses CRUCIBLE_API_KEY, then the sign-in
stored by crucible login for api_url, then api_key from the config
file.
Raises:
| Type | Description |
|---|---|
NotSignedInError
|
If there is no API key and no stored sign-in (a ValueError) |
health()
¶
Check API and database health without requiring authentication.
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
Readiness status with nested |
Raises:
| Type | Description |
|---|---|
ConnectionError
|
If the host is unreachable. |
live()
¶
Check whether the API process is running (no DB check, no auth).
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
{"status": "ok"} |
login(method='auto', store=None, open_browser=True, notify=print)
¶
Sign in with a browser and use that session from now on.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
method
|
str
|
'browser' (this computer's browser), 'paste' (any browser; you paste the code its page shows, for when the browser cannot reach this machine), 'device' (a code approved in any browser, for SSH or headless machines), or 'auto', which picks the browser when one is available here. |
'auto'
|
store
|
Optional[str]
|
Where to keep the tokens: 'auto' (the OS keyring, else a 0600 file), 'keyring', 'file', or 'memory' (this client only). Defaults to the auth_store setting. |
None
|
open_browser
|
bool
|
Open the browser automatically for the browser method. |
True
|
notify
|
Callable[[str, str], None]
|
Called with (message, url) to show the person where to go. |
print
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
{'user_unique_id', 'store', 'grant'} |
logout()
¶
End and forget the sign-in stored for this API address.
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
False when there was no stored sign-in. |
whoami()
¶
Return full auth context for the current API key.
Delegates to client.account.whoami(). Kept here for backward compatibility and because it spans the account context rather than a specific resource.
refresh_profile()
¶
Re-read authorization and capabilities from /account/profile.
get(resource_mfid, resource_type=None, include_metadata=False, include_links=False, include_owner=True, include_datasets=False)
¶
Get a resource by ID with automatic type detection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
resource_mfid
|
str
|
Resource MFID |
required |
resource_type
|
str
|
Resource type ('sample', 'dataset', 'project', or '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
|
include_owner
|
bool
|
Resolve the owner into a public-safe user object (default: True) |
True
|
include_datasets
|
bool
|
For samples, also embed the linked dataset records (default: False). Deprecated by the API: use include_links. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Optional[Dict]
|
Resource data |
Raises:
| Type | Description |
|---|---|
ValueError
|
If resource type is unknown or not supported |
get_resource_type(resource_mfid)
¶
Determine the type of a resource.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
resource_mfid
|
str
|
Resource MFID |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
resource_type |
get_links(resource_mfid)
¶
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": "...", "direction": "source|target|undirected", "relationship_type": "is_derived_from|is_part_of|null"}, ...]
direction says which end of the stored parent -> child edge this
resource is, relative to the one you asked about: "source" means it is
the parent, "target" the child. Dataset/sample associations have no
hierarchy and are always "undirected". relationship_type is the kind
of link, stored on the link row and oriented child-relative-to-parent;
it is null on associations and on links created before typing existed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
resource_mfid
|
str
|
Dataset or sample MFID |
required |
Returns:
| Name | Type | Description |
|---|---|---|
list |
list
|
Link objects, or empty list if none |
link(parent_mfid, child_mfid, relationship_type=None)
¶
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_mfid
|
str
|
Parent resource MFID |
required |
child_mfid
|
str
|
Child resource MFID |
required |
relationship_type
|
str
|
Kind of link, one of crucible.constants.RELATIONSHIP_TYPES. Only meaningful for dataset-to-dataset and sample-to-sample links; a dataset/sample association has no hierarchy to describe. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
Information about the created link |
Raises:
| Type | Description |
|---|---|
ValueError
|
If resource types cannot be determined, the combination is invalid, or relationship_type is given for a dataset/sample association |
unlink(resource_mfid_a, resource_mfid_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 |
|---|---|---|---|
resource_mfid_a
|
str
|
First dataset or sample MFID |
required |
resource_mfid_b
|
str
|
Second dataset or sample MFID |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
Deletion confirmation |
Raises:
| Type | Description |
|---|---|
ValueError
|
If resource types cannot be determined or combination is invalid. |