ump_sdk

package ump-sdk

ump_sdk: thin shared runtime for UMP POC services.

Read the ump-sdk guide first for the main entry points.

Modules

Module	What it holds
ump_sdk.adapter_client	Typed client for the engine adapter contract (ump_spec.adapter).
ump_sdk.client	Typed httpx clients for ump-core (blueprint “ump-core API”).
ump_sdk.errors	Client-side typed error for RFC 9457 problems returned by any UMP service.
ump_sdk.jobs	Tiny in-process background job helper (Temporal stand-in) with step history.
ump_sdk.ports	Port registry for the POC suite (blueprint “Repository layout”).
ump_sdk.scope	Who is calling, and which clients and actions they may touch (IAP/OIDC stand-in, read from core).
ump_sdk.service	FastAPI app factory shared by every UMP POC service.
ump_sdk.settings	Shared settings (pydantic-settings). Env prefix UMP_.

Re-exports

Documented on the page of the module that defines them.

Name	Kind	Summary
ADAPTERS	constant
ADAPTER_KINDS	constant	Adapter kind per blueprint adapter (ump_spec.adapter.AdapterKind). Core seeds its engine registry from this table; experiments are an adapter kind, not a model family.
APPS	constant
ENDPOINTS	constant
OPS_ROLES	constant	Roles that may read and cancel any job (operations work; they still author no client work).
PORTS	constant
PRINCIPAL_HEADER	constant
SERVICE_KINDS	constant
SERVICE_PRINCIPALS	constant
AdapterClient	class
AsyncAdapterClient	class
AsyncCoreClient	class	Async client: same methods, awaitable.
CallerScope	class
CoreClient	class	Sync client. principal sets X-UMP-Principal (e.g. user:maya.chen).
JobContext	class
JobRunner	class
Principal	class
ProblemError	class	Raised by the SDK clients for any HTTP status >= 400. problem is the parsed RFC 9457 body (or a synthesised one when the server did not send problem+json).
UmpSettings	class
accepted	function	Spec §19: 202 Accepted with Location: {prefix}/{id} for a call that runs as a job. An app’s body is {job_id, state, status_url, events_url, job} plus extra; an adapter’s (adapter=True) is exactly the engine profile’s JobAccepted {job_id, state, status_url}. status_url equals Location.
base_url	function	Base URL for a service: env override UMP_<NAME>_URL or http://localhost:<port>.
caller_scope	function	The caller’s scope from core /v1/whoami (cached ttl seconds per principal; fresh skips the cache, e.g. after the caller created a client and was bound to it).
caller_scope_sync	function	Sync twin of :func:caller_scope for sync route handlers (planner).
create_app	function	Build a FastAPI app with the UMP conventions. name should be a key of ports.PORTS.
error_response	function
get_gate_mode	function	FastAPI dependency: the UMP-On-Gate-Fail header (X-UMP-On-Gate-Fail is the deprecated spelling), else fallback. Any other value is 422 SCHEMA_INVALID. The mode is echoed on the response unless the route records a stricter effective mode with set_gate_mode_echo.
get_principal	function	FastAPI dependency: principal: Principal = Depends(get_principal).
get_settings	function
invalidate_scope_cache	function
mount_job_routes	function	GET {prefix}, GET {prefix}/{id}, GET {prefix}/{id}/events (SSE), POST {prefix}/{id}:cancel.
mount_unavailable	function	Spec §8 engine profile: mount POST /v1/<op> answering 501 OPERATION_UNAVAILABLE for every ADAPTER_OPERATIONS request that operations (the adapter’s metadata) does not mark built_in, unless the app already routes that path. The problem’s suggested_action names the nearest working operation (ump_spec.adapter.unavailable_suggestion); reason is added to the detail. Returns the requests mounted, in contract order. Call it after the app’s own routes.
port	function
problem_response	function
request_gate_mode	function	The request’s on_gate_fail from the body member or the header (spec §19), as a per-gate map; None when the request names none. Both present and different is 422 GATE_MODE_CONFLICT.
require_client_scope	function	Raise 403 unless client_id is in the caller’s scope (asks core again before refusing, so a client the caller just created counts). Returns the scope.
run	function	python -m <pkg> helper: serve on the registry port for name.
scope_from_whoami	function
set_gate_mode_echo	function	Record the mode a route applied; create_app echoes it in UMP-On-Gate-Fail (spec §19).

Constants

Name	Type	Value	Description
GATE_MODE_HEADER		'UMP-On-Gate-Fail'	Spec §19 gate-mode header (string form only). Servers echo the effective mode in it.
IDEMPOTENCY_HEADER		'Idempotency-Key'
LEGACY_GATE_MODE_HEADER		'X-UMP-On-Gate-Fail'	Deprecated spelling, still read by get_gate_mode for one cycle; clients send GATE_MODE_HEADER.