StudioClient
junjo.studio.StudioClient
Kind: Class
SDK version: 0.67.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 only for an explicit full trace-evidence request. |
_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.
This is the only client operation that uses the larger evidence byte budget. Listing, detail, comparison, 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_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.