SDK protocol prototype¶

Not a supported distribution

These contracts are preserved for convergence work. Their three HTTP routes have no server implementation in this repository, so the SDK wheel is release-blocked.

Client¶

zeroth.sdk ¶

HTTP client for Zeroth's hosted optimization API.

ZerothClient ¶

ZerothClient(
    *,
    api_key: str,
    base_url: str,
    timeout: float = 10.0,
    backtest_timeout: float = 120.0,
    http_client: Client | None = None,
)

Send workflow evidence and decision requests to a Zeroth service.

record_execution ¶

record_execution(event: ExecutionEvent) -> dict[str, Any]

Record the measured cost of one workflow step.

record_outcome ¶

record_outcome(event: OutcomeEvent) -> dict[str, Any]

Attach a business outcome to a workflow run.

create_outcome_definition ¶

create_outcome_definition(
    definition: OutcomeDefinition,
) -> dict[str, Any]

Declare the immutable success rule for a workflow version (Admin only).

record_charge_cost_revision ¶

record_charge_cost_revision(
    revision: ChargeCostRevision,
) -> dict[str, Any]

Append a replacement cost assertion for an existing physical charge.

list_charge_cost_revisions ¶

list_charge_cost_revisions(
    charge_id: str, *, limit: int = 100
) -> list[dict[str, Any]]

Read the most recent source assertions, newest first (at most 1000).

create_backtest ¶

create_backtest(request: BacktestRequest) -> dict[str, Any]

Submit a candidate workflow change for economic backtesting.

list_backtests ¶

list_backtests() -> list[dict[str, Any]]

List immutable hosted backtest results for the current project.

compare_versions ¶

compare_versions(
    request: VersionComparisonRequest,
) -> dict[str, Any]

Request an evidence-gated economic decision for a workflow change.

create_decision_schedule ¶

create_decision_schedule(
    request: DecisionScheduleRequest,
) -> dict[str, Any]

Create a recurring economic workflow-version comparison.

list_decision_schedules ¶

list_decision_schedules() -> list[dict[str, Any]]

List recurring economic comparisons for the current project.

deactivate_decision_schedule ¶

deactivate_decision_schedule(
    schedule_id: str,
) -> dict[str, Any]

Idempotently deactivate one recurring economic comparison.

list_decisions ¶

list_decisions(
    *, workflow: str | None = None
) -> list[dict[str, Any]]

List retained economic decisions, optionally for one workflow.

create_model_migration_decision ¶

create_model_migration_decision(
    request: ProbabilisticMigrationRequest,
) -> dict[str, Any]

Simulate and retain a risk-calibrated model migration decision.

list_model_migration_decisions ¶

list_model_migration_decisions(
    *, workload: str | None = None
) -> list[dict[str, Any]]

List retained probabilistic model migration decisions.

refresh_model_migration_decision ¶

refresh_model_migration_decision(
    request: MigrationEvidenceRefreshRequest,
) -> dict[str, Any]

Harvest current telemetry, simulate, and retain a fresh decision.

create_probabilistic_decision_schedule ¶

create_probabilistic_decision_schedule(
    request: ProbabilisticDecisionScheduleRequest,
) -> dict[str, Any]

Schedule fresh evidence harvesting and probabilistic reevaluation.

deactivate_probabilistic_decision_schedule ¶

deactivate_probabilistic_decision_schedule(
    schedule_id: str,
) -> dict[str, Any]

Idempotently deactivate one probabilistic reevaluation schedule.

create_randomized_rollout ¶

create_randomized_rollout(
    request: RandomizedRolloutRequest,
) -> dict[str, Any]

Create a randomized verification rollout for a retained decision.

stop_randomized_rollout ¶

stop_randomized_rollout(rollout_id: str) -> dict[str, Any]

Idempotently stop one randomized rollout.

assign_randomized_rollout ¶

assign_randomized_rollout(
    rollout_id: str,
    *,
    subject_id: str,
    cohort: str = "default",
) -> dict[str, Any]

Get the persisted random assignment for one stable subject.

verify_randomized_rollout ¶

verify_randomized_rollout(
    rollout_id: str, request: RandomizedRolloutVerifyRequest
) -> dict[str, Any]

Verify causal effects and append calibration observations.

create_decision_report ¶

create_decision_report(decision_id: str) -> dict[str, Any]

Create or retrieve the immutable PDF for a retained decision.

download_decision_report ¶

download_decision_report(report_id: str) -> bytes

Download one authenticated PDF decision artifact.

deliver_decision_report ¶

deliver_decision_report(
    report_id: str, request: DecisionReportDeliveryRequest
) -> dict[str, Any]

Email an exact report artifact or authenticated report link.

close ¶

close() -> None

Close the underlying HTTP transport.

ZerothAPIError ¶

ZerothAPIError(
    *,
    response: Response,
    detail: str,
    request_id: str | None,
    correlation_id: str | None,
)

Bases: HTTPStatusError, ZerothSDKError

A sanitized non-success API response compatible with HTTPX catches.

ZerothAuthenticationError ¶

ZerothAuthenticationError(
    *,
    response: Response,
    detail: str,
    request_id: str | None,
    correlation_id: str | None,
)

Bases: ZerothAPIError

The API rejected the caller's credentials with HTTP 401.

ZerothAuthorizationError ¶

ZerothAuthorizationError(
    *,
    response: Response,
    detail: str,
    request_id: str | None,
    correlation_id: str | None,
)

Bases: ZerothAPIError

The authenticated caller is not authorized (HTTP 403).

ZerothConflictError ¶

ZerothConflictError(
    *,
    response: Response,
    detail: str,
    request_id: str | None,
    correlation_id: str | None,
)

Bases: ZerothAPIError

The request conflicts with current resource state (HTTP 409).

ZerothEntitlementError ¶

ZerothEntitlementError(
    *,
    response: Response,
    detail: str,
    request_id: str | None,
    correlation_id: str | None,
)

Bases: ZerothAPIError

The requested capability requires an unavailable entitlement (HTTP 402).

ZerothNotFoundError ¶

ZerothNotFoundError(
    *,
    response: Response,
    detail: str,
    request_id: str | None,
    correlation_id: str | None,
)

Bases: ZerothAPIError

The tenant-scoped resource was not found (HTTP 404).

ZerothRateLimitError ¶

ZerothRateLimitError(
    *,
    response: Response,
    detail: str,
    request_id: str | None,
    correlation_id: str | None,
)

Bases: ZerothAPIError

The API rate limit rejected the request with HTTP 429.

ZerothSDKError ¶

Bases: Exception

Base class for failures raised by the Zeroth SDK.

ZerothServerError ¶

ZerothServerError(
    *,
    response: Response,
    detail: str,
    request_id: str | None,
    correlation_id: str | None,
)

Bases: ZerothAPIError

The API failed with an HTTP 5xx response.

ZerothTransportError ¶

ZerothTransportError(*, original_error: RequestError)

Bases: RequestError, ZerothSDKError

A sanitized network transport failure compatible with HTTPX catches.

ZerothValidationError ¶

ZerothValidationError(
    *,
    response: Response,
    detail: str,
    request_id: str | None,
    correlation_id: str | None,
)

Bases: ZerothAPIError

The API rejected request validation with HTTP 422.

Protocol¶

zeroth.protocol ¶

Public request and event contracts shared with Zeroth Cloud.

BacktestCase ¶

Bases: BaseModel

Ephemeral input and expected output used for one bounded replay.

BacktestRequest ¶

Bases: BaseModel

Candidate workflow change and the boundaries used to judge it.

DecisionPolicy ¶

Bases: BaseModel

Evidence and economic constraints for a workflow-version decision.

DecisionScheduleRequest ¶

Bases: BaseModel

Create a recurring economic comparison for two workflow versions.

EconomicConstraints ¶

Bases: BaseModel

Quality and economic boundaries a backtest candidate must satisfy.

ExecutionEvent ¶

Bases: BaseModel

Caller-reported cost and latency for one workflow step; missing cost is unknown.

ForecastCalibrationObservation ¶

Bases: BaseModel

One forecast-versus-observed period used for server-side calibration.

ForecastReadiness ¶

Bases: BaseModel

Calibration and drift status attached to a forecast evidence snapshot.

MigrationEvidence ¶

Bases: BaseModel

Paired model evidence and observed demand periods for one workload.

MigrationObservation ¶

Bases: BaseModel

One paired incumbent or candidate outcome used by the scenario engine.

MigrationRiskPolicy ¶

Bases: BaseModel

Customer-owned chance constraints and CVaR limit for model migration.

OutcomeEvent ¶

Bases: BaseModel

Business acceptance signal associated with a workflow run.

ProbabilisticMigrationRequest ¶

Bases: BaseModel

Request a retained Monte Carlo model-migration recommendation.

VersionComparisonRequest ¶

Bases: BaseModel

Request an evidence-gated comparison of two exact workflow versions.

SourceWindowInventory ¶

Bases: BaseModel

digest ¶

digest() -> str

Canonical request assertion, without retaining another raw inventory copy.

execution_ids_digest ¶

execution_ids_digest(ids: list[str]) -> str

Hash exact unique IDs in UTF-8 byte order, shared with explicit HTTP callers.