Skip to content

Execution

Stable

Covered by the 1.0 API freeze (proposal 0029): no breaking change before 2.0.

OunceStore

Bases: Protocol

What the framework needs from shared storage.

shared property

shared: bool

True when put_if_absent is atomic across processes.

put_if_absent async

put_if_absent(ns: str, key: str, value: Mapping[str, Any], *, ttl_s: float) -> bool

Store value only if key is unset. True if this call stored it.

MemoryStore

MemoryStore(*, clock: Callable[[], float] = time.monotonic, max_entries: int = MAX_MEMORY_ENTRIES)

In-process store. Atomic within one event loop; lost on restart.

Expired records are removed on reads and, every SWEEP_INTERVAL_S, on writes. At most max_entries records are kept; when full, the record that expires soonest is dropped, so a caller cannot grow the process without bound.

KeyValueStore

KeyValueStore(kv: Any)

Any py-key-value-aio store. put_if_absent is atomic per process only.

RedisStore

RedisStore(client: Any, *, prefix: str = 'ouncemcp')

A store on a redis.asyncio.Redis client; claims are atomic across replicas.

Idempotency dataclass

Idempotency(ttl_s: float = 86400, grace_s: float = 60, wait_s: float = 5)

Settings for one tool.

Attributes:

Name Type Description
ttl_s float

How long a finished write's result is replayed to duplicates.

grace_s float

How long a write may keep running after the caller's deadline.

wait_s float

How long a duplicate waits for a running original before it is told to retry (never longer than its own deadline).

Limits dataclass

Limits(default_deadline_ms: int = 30000, max_request_bytes: int = 65536, max_depth: int = 16, max_concurrency: int = 8, max_error_chars: int = DEFAULT_MAX_ERROR_CHARS)

Bounds on what one call may cost the server.

Attributes:

Name Type Description
default_deadline_ms int

Deadline for a tool that does not set deadline_ms.

max_request_bytes int

Largest JSON-encoded argument object accepted.

max_depth int

Deepest nesting of objects and lists accepted in arguments.

max_concurrency int

Calls one principal may have in flight; more are refused at once.

max_error_chars int

Longest error message sent to a caller.

RetryPolicy dataclass

RetryPolicy(max_attempts: int = 3, base_delay: float = 0.1, max_delay: float = 2.0, jitter: float = 0.2, sleep: Callable[[float], Awaitable[None]] = anyio.sleep)

How a read is retried after a transient or rate-limit failure.

Only tools declared Effect.READ are ever retried. Writes are never retried automatically. Every wait must fit inside the call's remaining deadline, or the failure is returned at once.

Attributes:

Name Type Description
max_attempts int

Total tries, including the first. 1 turns retries off.

base_delay float

Wait before the second try, in seconds. It doubles each time.

max_delay float

Longest backoff wait. Does not cap an upstream Retry-After.

jitter float

Fraction (0 to 1) by which each backoff is randomly shortened or lengthened, so many callers do not retry together.

sleep Callable[[float], Awaitable[None]]

How to wait. Replaceable in tests.

delay

delay(attempt: int, retry_after: float | None = None) -> float

Seconds to wait after failed attempt number attempt (1 is the first).

An upstream retry_after wins over the backoff.

WriteAttempt dataclass

WriteAttempt(tool: str, principal: str, arguments: Mapping[str, Any] = dict(), reason: str = 'write_status_unknown')

What a resolver is told about the write that timed out.

WriteResolver

Bases: Protocol

resolve async

resolve(attempt: WriteAttempt) -> BaseModel | Mapping[str, Any] | None

Return the write's result if it is known to have been applied, else None.

JobResult dataclass

JobResult(summary: BaseModel | dict[str, Any] | None = None, items: Sequence[Any] | None = None)

What a job returns: a small summary and, optionally, many items that are stored behind a handle instead of being sent at once.