StudioClient
junjo.studio.StudioClient
Kind: Class
SDK version: 0.69.0
Documentation channel: Stable release
Signature
Section titled “Signature”StudioClient(*, base_url: str, token: str | SecretStr | None = None, connect_timeout_seconds: float = 5.0, read_timeout_seconds: float = 30.0, write_timeout_seconds: float = 30.0, pool_timeout_seconds: float = 5.0, max_connections: int = 10, max_keepalive_connections: int = 5, retry_attempts: int = 3, retry_backoff_seconds: float = 0.25, max_control_response_bytes: int = _DEFAULT_CONTROL_RESPONSE_BYTES, max_evidence_response_bytes: int = _DEFAULT_EVIDENCE_RESPONSE_BYTES, transport: httpx.AsyncBaseTransport | None = None)One pooled, bounded Studio control/query client.
Evaluation operations use a separately scoped Studio control/query token. Ingestion API keys and Studio account passwords are not accepted by this interface. A token may be omitted only for unauthenticated capability and health inspection.
The client reuses one AsyncClient for its lifetime. It
applies explicit connection and timeout limits, consumes response streams
under byte budgets, and retries only transport failures or transient HTTP
statuses. Evaluation mutations are idempotently keyed by their explicit
Studio natural keys, so every retry sends the exact same payload.
Parameters
Section titled “Parameters”| Name | Type | Description | Default |
|---|---|---|---|
base_url |
str |
Studio origin, such as https://studio.example.com.Plain HTTP is accepted only for a loopback origin. |
|
token |
str | SecretStr | None |
Scoped Studio control/query token. It is sent as a Bearer token and is redacted from object representations and errors. |
None |
connect_timeout_seconds |
float |
Maximum connection-establishment time. | 5.0 |
read_timeout_seconds |
float |
Maximum wait for each response read. | 30.0 |
write_timeout_seconds |
float |
Maximum wait for request writes. | 30.0 |
pool_timeout_seconds |
float |
Maximum wait for a pooled connection. | 5.0 |
max_connections |
int |
Upper bound for all pooled connections. | 10 |
max_keepalive_connections |
int |
Upper bound for idle pooled connections. | 5 |
retry_attempts |
int |
Total attempts for retryable requests, including the first attempt. |
3 |
retry_backoff_seconds |
float |
Initial non-blocking exponential backoff. | 0.25 |
max_control_response_bytes |
int |
Byte budget for control API responses. | _DEFAULT_CONTROL_RESPONSE_BYTES |
max_evidence_response_bytes |
int |
Byte budget used for explicitly selected spans or complete trace evidence. |
_DEFAULT_EVIDENCE_RESPONSE_BYTES |
transport |
httpx.AsyncBaseTransport | None |
Optional HTTPX transport, primarily for deterministic tests or an explicitly managed application transport. |
None |
Members
Section titled “Members”close() -> NoneClose pooled connections.
get_health
Section titled “get_health”get_health() -> StudioHealthReturn Studio status and product version through bounded transport.
create_dataset
Section titled “create_dataset”create_dataset(request: DatasetCreate) -> DatasetReadCreate or retrieve a dataset by application key and dataset key.
list_datasets
Section titled “list_datasets”list_datasets(*, application_key: str | None = None, cursor: str | None = None, limit: int = 50) -> DatasetListReturn one bounded cursor page of datasets.
The method intentionally returns one page rather than silently
hydrating an unbounded collection. Callers must explicitly continue
with next_cursor.
get_dataset
Section titled “get_dataset”get_dataset(dataset_id: str) -> DatasetDetailReturn a dataset and its complete bounded case membership.
add_case
Section titled “add_case”add_case(dataset_id: str, request: CaseCreate) -> CaseReadAppend or retrieve one idempotently keyed case in a draft dataset.
lock_dataset
Section titled “lock_dataset”lock_dataset(dataset_id: str) -> DatasetReadIdempotently lock one dataset against further case changes.
start_run
Section titled “start_run”start_run(request: RunStart) -> RunDetailCreate or retrieve a run by dataset and stable request key.
list_runs
Section titled “list_runs”list_runs(*, dataset_id: str | None = None, target_kind: TargetKind | None = None, target_key: str | None = None, input_version: int | None = None, evaluation_name: str | None = None, cursor: str | None = None, limit: int = 50) -> RunListReturn one bounded page scoped by conjunctive case identity filters.
get_run
Section titled “get_run”get_run(run_id: str) -> RunDetailReturn one run and its exact case-attempt membership.
compare_runs
Section titled “compare_runs”compare_runs(baseline_run_id: str, candidate_run_id: str, *, target_kind: TargetKind | None = None, target_key: str | None = None, input_version: int | None = None, evaluation_name: str | None = None) -> RunComparisonFetch and compare two runs without hydrating full trace evidence.
get_attempt
Section titled “get_attempt”get_attempt(attempt_id: str) -> AttemptDetailReturn one attempt with its run, dataset, and case context.
bind_attempt_evidence
Section titled “bind_attempt_evidence”bind_attempt_evidence(attempt_id: str, evidence: ExecutionEvidenceReference) -> AttemptReadIdempotently bind exact execution evidence to an attempt.
record_attempt_result
Section titled “record_attempt_result”record_attempt_result(attempt_id: str, result: AttemptResultWrite) -> AttemptReadIdempotently record one terminal evaluation judgment.
resolve_execution
Section titled “resolve_execution”resolve_execution(execution: SemanticExecutionReference) -> ExecutionResolutionReadResolve exact semantic identity to a received Studio owner span.
Raises
Section titled “Raises”| Exception | Description |
|---|---|
ExecutionEvidencePending |
When Studio has not indexed the execution. |
ExecutionIdentityAmbiguous |
When identity matches more than one owner span. |
get_trace_evidence
Section titled “get_trace_evidence”get_trace_evidence(trace_id: str) -> TraceEvidenceReadExplicitly hydrate complete evidence for one trace.
Complete trace and selected-span operations use the larger evidence byte budget. Listing, detail, comparison, manifest, and membership operations remain bounded control projections.
get_attempt_evidence
Section titled “get_attempt_evidence”get_attempt_evidence(attempt_id: str) -> AttemptEvidenceJoin an attempt to its exact complete Studio trace evidence.
get_attempt_evidence_manifest
Section titled “get_attempt_evidence_manifest”get_attempt_evidence_manifest(attempt_id: str) -> AttemptEvidenceManifestReturn bounded trace structure and selectable identities for an Attempt.
This is the normal first evidence query after inspecting the Attempt control record. Full prompts, responses, state, events, and stack traces remain available through selected-span or complete-trace hydration.
Parameters
Section titled “Parameters”| Name | Type | Description | Default |
|---|---|---|---|
attempt_id |
str |
Studio evaluation Attempt record ID. |
Returns
Section titled “Returns”AttemptEvidenceManifest: Bounded subject, trace, failure, executable, operation, Store, relationship, and diagnostic summaries.
Raises
Section titled “Raises”| Exception | Description |
|---|---|
AttemptEvidenceUnavailable |
If the Attempt has no evidence binding. |
ExecutionEvidencePending |
If Studio has not indexed the bound trace evidence yet. |
ExecutionIdentityAmbiguous |
If the semantic execution identity resolves to more than one owner span. |
get_attempt_evidence_spans
Section titled “get_attempt_evidence_spans”get_attempt_evidence_spans(attempt_id: str, span_ids: Sequence[str]) -> AttemptEvidenceSpansReturn complete evidence for explicitly selected spans in one Attempt trace.
Requested identities are kept in caller order. Studio returns identities
absent from the bound trace in missing_span_ids rather than silently
discarding them.
Parameters
Section titled “Parameters”| Name | Type | Description | Default |
|---|---|---|---|
attempt_id |
str |
Studio evaluation Attempt record ID. | |
span_ids |
Sequence[str] |
Non-empty unique sequence of exact lowercase hexadecimal OpenTelemetry span IDs. |
Returns
Section titled “Returns”AttemptEvidenceSpans: Complete raw spans with only their directly associated semantic annotations, plus explicit missing identities.
Raises
Section titled “Raises”| Exception | Description |
|---|---|
AttemptEvidenceUnavailable |
If the Attempt has no evidence binding. |
ExecutionEvidencePending |
If Studio has not indexed the bound trace evidence yet. |
ExecutionIdentityAmbiguous |
If the semantic execution identity resolves to more than one owner span. |
get_evidence_membership
Section titled “get_evidence_membership”get_evidence_membership(evidence: ExecutionEvidenceReference, *, cursor: str | None = None, limit: int = 50) -> EvidenceMembershipListReturn one bounded page of exact evaluation membership.