Python API
The Python package remains ridge even though the distribution is named
ridge-core.
For inventory validation without application/state initialization, use the configuration validation CLI.
Agent hosts use RidgeService for workspace access, delegated tasks, and
supervision. Start with the runnable process handoff
for a complete parent/child lifecycle.
Application code should begin with RidgeService:
from ridge import RidgeService
ridge = RidgeService.from_config("ridge.yaml")
for resource in ridge.list_resources():
print(resource.name, resource.supported_operations, resource.allowed_operations)
ridge.copy("project-files:README.md", "artifacts:README.md")
page = ridge.list_data("artifacts", limit=20)
Job discovery returns a JobPage containing JobSummary values:
page = ridge.list_jobs(limit=20)
for job in page.jobs:
print(job.id, job.status)
if page.next_cursor is not None:
page = ridge.list_jobs(limit=20, cursor=page.next_cursor)
Use ridge.inspect_job(job_id) for results, errors, and cancellation intent.
For execution, inspect result["exit_code"] before using the outputs: job status
succeeded means the operation completed, even if the command returned nonzero. See
job discovery for ordering, bounds, and policy changes.
The top-level ridge exports are the supported convenience API. The
ridge.resource, ridge.provider, ridge.model, and ridge.conformance
modules are also public extension surfaces for provider authors. Other modules,
including ridge.backends, are implementation details.
Use RidgeService.from_config() when permissions in the YAML document must be
applied. load_registry() intentionally loads only resource inventory;
constructing a service directly from that registry selects unrestricted mode.
from_config() also enables shared durable coordination. A directly constructed
service without a job manager has no coordination store. For multi-call work,
use acquire_locks([JobScope(resource, Operation.DATA_WRITE), ...]) and pass the
returned token to with_lock(token). That returns a separate service view, so
concurrent callers do not mutate one another's session selection. Close ownership
with release_locks(token); see session semantics.
Use LockRequest(resource, operation, path) instead of JobScope to reserve a
file/tree or exact object. Both acquire_locks and managed session helpers accept
mixed whole-resource and path requests. Ridge derives claims; calls must fit them.
Lock inspection exposes structured {domain, scope, mode} claim lists. Providers
may implement public FootprintCapability using Footprint values for pure action
planning; callers do not supply footprints. See provider planning.
Prefer with ridge.lock_session(scopes) as session: for host-owned workflows;
session.service attaches the token and a background thread renews the lease.
ManagedMCPSession(client, scopes) provides an asyncio context with
session.call_tool(...) for MCP hosts. Both are single-use and fail closed on
renewal failure. See managed caller sessions
for lifecycle, cancellation, and integration requirements.
Delegated tasks
from ridge import AccessGrant, Operation, RidgeService
operator = RidgeService.from_config("ridge.yaml")
issued = operator.create_scope(
[
AccessGrant("inputs", frozenset({Operation.DATA_READ, Operation.DATA_STAT})),
]
)
child = RidgeService.from_config("ridge.yaml", scope_token=issued.token)
print(child.inspect_access())
operator.revoke_scope(issued.scope.id)
The workspace must permit and explicitly delegate these operations. Store the
returned token securely; it is not returned by inspection. Bound service methods
reload configuration and recheck lifecycle for each request. Python binding is
explicit: from_config() does not read RIDGE_SCOPE_TOKEN; CLI/MCP entry points
own environment/file transport. None deliberately selects operator mode in trusted
Python code; empty or invalid strings fail closed.
See task access for
attenuation, expiry, visibility, and the distinction from lock sessions.
AccessGrant(..., data_root="outputs/task-a") narrows data access relative to the
parent view. The directory is validated when used, not created at issuance.
Omitting data_root inherits the parent's view; compute is not narrowed.
Managed sessions
ridge.ManagedSession
Single-use synchronous workflow scope with a renewing, token-bound service.
_deadline = 0.0
instance-attribute
_entered = False
instance-attribute
_error = None
instance-attribute
_lease = lease_seconds
instance-attribute
_open = False
instance-attribute
_owner = service
instance-attribute
_scopes = tuple(scopes)
instance-attribute
_service = None
instance-attribute
_stop = threading.Event()
instance-attribute
_thread = None
instance-attribute
_token = ''
instance-attribute
_wait = wait_seconds
instance-attribute
service
property
__enter__()
__exit__(exc_type, exc, traceback)
__init__(service, scopes, *, lease_seconds=300, wait_seconds=0)
_renew()
check()
Raise when closed or unhealthy; does not interrupt already-admitted work.
ridge.ManagedMCPSession
Asyncio caller scope over an already-connected Ridge MCP client.
The caller must keep the client and event loop alive throughout this scope. Tool results retain the MCP SDK's ordinary error/result representation.
_TOOLS = frozenset({'execute', 'list_data', 'read_data', 'write_data', 'delete_data', 'stat_data', 'copy'})
class-attribute
instance-attribute
_client = client
instance-attribute
_deadline = 0.0
instance-attribute
_entered = False
instance-attribute
_error = None
instance-attribute
_lease = lease_seconds
instance-attribute
_open = False
instance-attribute
_scopes = tuple(scopes)
instance-attribute
_task = None
instance-attribute
_token = ''
instance-attribute
_wait = wait_seconds
instance-attribute
__aenter__()
async
__aexit__(exc_type, exc, traceback)
async
__init__(client, scopes, *, lease_seconds=300, wait_seconds=0)
_close(body)
async
_control(name, arguments)
async
_renew()
async
call_tool(name, arguments=None)
async
Dispatch a Ridge resource operation with this session's token.
check()
Check health before dispatching the next workflow action.
Application service
ridge.application.RidgeService
Frontend-neutral Ridge workflows over a resource registry.
_access = None
instance-attribute
_authorization = authorization or AuthorizationPolicy.unrestricted()
instance-attribute
_binding = None
instance-attribute
_jobs = jobs
instance-attribute
_loaded = None
instance-attribute
_lock_token = None
instance-attribute
_managed_check = None
instance-attribute
_planner = FootprintPlanner(registry, jobs.coordination.keys if jobs else {})
instance-attribute
_registry = registry
instance-attribute
__init__(registry, authorization=None, jobs=None)
_authorize(resource, operation, context)
_authorize_job(job)
_authorize_scopes(scopes)
_compute(resource, operation, context)
_coordination()
_data(resource, operation, context)
_execute_to_logs(resource, argv, stdout, stderr, *, cwd=None, timeout_seconds=None)
Execute for the local job supervisor, streaming when the backend supports it.
_from_configuration(loaded)
classmethod
_job_allowed(job)
_job_manager()
_local_scopes(scopes)
_lock_scopes(value)
staticmethod
_operation(scopes, paths=None)
_operation_token()
_prepare_copy(source, destination, *, background=False)
_prepare_delete(resource, path, recursive, *, background=False)
_reconcile_jobs()
_request_service()
_scope_configuration()
_scoped_request(loaded, access, token)
classmethod
_submission_claims(scopes, paths)
_transfer(resource, operation, context)
_unsupported(resource, operation)
staticmethod
_validate_timeout(timeout_seconds)
staticmethod
_with_permissions(inspection)
acquire_locks(scopes, *, lease_seconds=300, wait_seconds=0)
cancel_job(job_id)
copy(source, destination)
create_scope(grants, *, expires_at=None)
Derive task authority; the returned bearer handle is disclosed only once.
delete_data(resource, path, *, recursive=False)
Delete an exact entry; recursive trees are non-atomic and never rolled back.
execute(resource, argv, *, cwd=None, env=None, timeout_seconds=None)
force_release_lock(identity, *, reason)
from_config(config_path, *, scope_token=None)
classmethod
inspect_access()
Report effective use and delegation authority, without bearer handles.
inspect_job(job_id)
inspect_lock(identity)
inspect_resource(resource)
inspect_scope(identity)
list_data(resource, path=None, *, cursor=None, limit=100)
List directory children or exact prefix matches, according to addressing.
list_jobs(*, limit=50, cursor=None)
Return authorized summaries, newest first; resume with the page's opaque cursor.
list_locks(*, cursor=None, limit=100)
list_resources()
list_scopes(*, cursor=None, limit=100)
lock_session(scopes, *, lease_seconds=300, wait_seconds=0)
Own acquisition, automatic renewal, and release around a Python workflow.
read_data(resource, path, *, max_bytes=None)
read_job_log(job_id, stream, *, offset=0, limit=64 * 1024)
release_locks(token)
renew_locks(token)
revoke_scope(identity)
Close scope admission without cancelling work or releasing resource claims.
stat_data(resource, path)
submit_copy(source, destination, *, idempotency_key=None)
submit_delete(resource, path, *, recursive=False, idempotency_key=None)
Submit one deletion attempt against the path/key as it exists when the worker runs.
submit_execution(resource, argv, *, cwd=None, env=None, timeout_seconds=None, idempotency_key=None)
submit_write(resource, path, content, *, idempotency_key=None)
with_lock(token)
Return a request-scoped service using an explicit coordination session.
write_data(resource, path, content)
Authorization
ridge.authorization.AuthorizationPolicy
An unrestricted policy or exact, default-deny resource grants.
_grants = MappingProxyType(dict(grants or {}))
instance-attribute
_unrestricted = grants is None
instance-attribute
unrestricted_mode
property
__init__(grants=None)
allows(resource, operation)
authorize(request)
exact(grants)
classmethod
unrestricted()
classmethod
ridge.authorization.AuthorizationRequest
dataclass
One resource operation and the request context used to authorize it.
context
instance-attribute
operation
instance-attribute
resource
instance-attribute
__init__(resource, operation, context)
create(resource, operation, context=None)
classmethod
ridge.authorization.Authorizer
Bases: Protocol
Application-boundary authorization contract.
allows(resource, operation)
authorize(request)
Resource capabilities
ridge.resource.ResourceCapabilities
dataclass
Typed capability implementations exposed by one named resource.
addressing
property
compute = None
class-attribute
instance-attribute
data_views = None
class-attribute
instance-attribute
delete = None
class-attribute
instance-attribute
filesystem = None
class-attribute
instance-attribute
footprint_guard = None
class-attribute
instance-attribute
footprints = None
class-attribute
instance-attribute
operations
property
storage = None
class-attribute
instance-attribute
transfer = None
class-attribute
instance-attribute
__init__(compute=None, filesystem=None, storage=None, transfer=None, delete=None, data_views=None, footprints=None, footprint_guard=None)
__post_init__()
ridge.resource.ComputeCapability
Bases: Protocol
exec(argv, *, cwd=None, env=None, timeout_seconds=None)
ridge.resource.FilesystemCapability
Bases: Protocol
list(path='.')
read(path, *, max_bytes=None)
stat(path)
write(path, content)
ridge.resource.StorageCapability
Bases: Protocol
list_objects(prefix='', *, cursor=None, limit=1000)
read_object(key, *, max_bytes=None)
stat_object(key)
write_object(key, content)
ridge.resource.TransferCapability
Bases: Protocol
open_transfer_destination(path, kind)
open_transfer_source(path)
ridge.resource.DeleteCapability
Bases: Protocol
Optional exact-path/key deletion using the resource's data addressing model.
delete(path, *, recursive=False)
ridge.model.DeleteResult
dataclass
Bounded outcome; acknowledged does not assert prior existence (object storage).
outcome
instance-attribute
__init__(outcome)
ridge.model.LockRequest
dataclass
Bases: JobScope
Reserve an operation at a file/tree path, or the whole resource when omitted.
path = None
class-attribute
instance-attribute
__init__(resource, operation, path=None)
__post_init__()
ridge.resource.FootprintGuardCapability
Bases: Protocol
Read-only validation under the complete candidate claims, before effects.
validate_footprint(path, roots)
Provider construction
ridge.provider.ProviderContext
dataclass
Core-owned context supplied while a provider constructs a resource.
config_dir
property
config_path
instance-attribute
__init__(config_path)
ridge.provider.ResourceProvider
Bases: Protocol
__call__(name, config, context)
ridge.provider.ResourceProviderRegistry
Resolves provider names to built-in or installed constructors.