Skip to content

Contracts and Adapters

contracts

Internal pipeline boundary and public optimization extension protocols.

Dataset

Bases: Protocol

Provide versioned evaluation examples.

version property 

version: str

Evaluator

Bases: Protocol

Convert an adapter output and example into metric observations.

evaluate async 

evaluate(output: Any, example: Any) -> Sequence[MetricValue]
Source code in src/tunarag/contracts.py 
27
async def evaluate(self, output: Any, example: Any) -> Sequence[MetricValue]: ...

SearchStrategy

Bases: Protocol

Suggest candidates and observe completed trials.

suggest async 

suggest() -> Candidate
Source code in src/tunarag/contracts.py 
33
async def suggest(self) -> Candidate: ...

observe async 

observe(candidate: Candidate, metrics: Sequence[MetricValue], usage: Sequence[UsageRecord]) -> None
Source code in src/tunarag/contracts.py 
35
36
37
38
39
40
async def observe(
    self,
    candidate: Candidate,
    metrics: Sequence[MetricValue],
    usage: Sequence[UsageRecord],
) -> None: ...

ReplayableSearchStrategy

Bases: Protocol

Restore strategy state from one durably reserved trial.

replay async 

replay(candidate: Candidate, metrics: Sequence[MetricValue], usage: Sequence[UsageRecord]) -> None
Source code in src/tunarag/contracts.py 
47
48
49
50
51
52
async def replay(
    self,
    candidate: Candidate,
    metrics: Sequence[MetricValue],
    usage: Sequence[UsageRecord],
) -> None: ...

Fingerprintable

Bases: Protocol

Expose secret-safe semantic configuration for identity checks.

fingerprint 

fingerprint() -> Any
Source code in src/tunarag/contracts.py 
59
def fingerprint(self) -> Any: ...

EventCallback

Bases: Protocol

Consume a durable event after its transaction commits.

on_event async 

on_event(event: StudyEvent) -> None
Source code in src/tunarag/contracts.py 
65
async def on_event(self, event: StudyEvent) -> None: ...

Cache

Bases: Protocol

Persist and retrieve versioned semantic results.

get 

get(key: CacheKey) -> CacheLookup
Source code in src/tunarag/contracts.py 
71
def get(self, key: CacheKey) -> CacheLookup: ...

put 

put(key: CacheKey, payload: bytes | bytearray | memoryview, *, privacy: CachePrivacy = STANDARD, ttl_seconds: float | None = None) -> CacheEntry
Source code in src/tunarag/contracts.py 
73
74
75
76
77
78
79
80
def put(
    self,
    key: CacheKey,
    payload: bytes | bytearray | memoryview,
    *,
    privacy: CachePrivacy = CachePrivacy.STANDARD,
    ttl_seconds: float | None = None,
) -> CacheEntry: ...