Scoring & Admin

Scoring

score

Score a data submission against target models. The scoring service downloads model weights and data, runs inference, and returns the results.

async def score(
    data_url: str,
    models: list[ModelManifest],
    target_embedding: list[float],
    data: Optional[bytes] = None,
    data_checksum: Optional[str] = None,
    data_size: Optional[int] = None,
    seed: int = 0,
) -> ScoreResult

Parameter	Type	Required	Default	Description
`data_url`	`str`	Yes	—	URL of the submission data
`models`	`list[ModelManifest]`	Yes	—	Model manifests to score against
`target_embedding`	`list[float]`	Yes	—	Target’s embedding vector
`data`	`bytes`	No	`None`	Raw data (alternative to URL fetch)
`data_checksum`	`str`	No	`None`	Expected data checksum
`data_size`	`int`	No	`None`	Expected data size
`seed`	`int`	No	`0`	Random seed for reproducibility

Returns: ScoreResult

Example

targets = await client.get_targets(status="open", limit=1)
target = targets[0]
manifests = await client.get_model_manifests(target)

result = await client.score(
    data_url="https://storage.example.com/data.bin",
    models=manifests,
    target_embedding=target.embedding,
)
print(f"Winner: model {result.winner}, distances: {result.distance}")

scoring_health

Check if the scoring service is healthy.

async def scoring_health() -> bool

Returns: bool — True if the service is reachable

Admin

advance_epoch

Force-advance the epoch (admin/localnet only).

async def advance_epoch() -> int

Returns: int — the new epoch number

Faucet

request_faucet

Request test tokens for an address.

async def request_faucet(address: str) -> FaucetResponse

Parameter	Type	Required	Default	Description
`address`	`str`	Yes	—	SOMA address to fund

Returns: FaucetResponse

Example

response = await client.request_faucet(kp.address())
print(f"Status: {response.status}")
for coin in response.coins_sent:
    print(f"  {coin.id}: {coin.amount} shannons")

Proxy

fetch_model

Download model weights from the validator proxy network.

async def fetch_model(model_id: str) -> bytes

Parameter	Type	Required	Default	Description
`model_id`	`str`	Yes	—	Model object ID

Returns: bytes — raw (encrypted) model weights

fetch_submission_data

Download submission data for a filled target from the validator proxy network.

async def fetch_submission_data(target_id: str) -> bytes

Parameter	Type	Required	Default	Description
`target_id`	`str`	Yes	—	Target object ID

Returns: bytes — raw submission data

Convenience Methods

commit_model

Commit a new model in a single call. Handles commitment computation, transaction building, signing, and execution.

async def commit_model(
    signer: Keypair,
    weights_url: str,
    encrypted_weights: bytes,
    commission_rate: int,
    stake_amount: Optional[int] = None,
) -> str

Parameter	Type	Required	Default	Description
`signer`	`Keypair`	Yes	—	Keypair to sign the transaction
`weights_url`	`str`	Yes	—	URL where encrypted weights will be hosted
`encrypted_weights`	`bytes`	Yes	—	Encrypted model weights
`commission_rate`	`int`	Yes	—	Commission rate in basis points
`stake_amount`	`int`	No	`None`	Stake in shannons (uses minimum if omitted)

Returns: str — the assigned model ID

reveal_model

Reveal a previously committed model.

async def reveal_model(
    signer: Keypair,
    model_id: str,
    weights_url: str,
    encrypted_weights: bytes,
    decryption_key: str,
    embedding: list[float],
) -> None

Parameter	Type	Required	Default	Description
`signer`	`Keypair`	Yes	—	Keypair to sign
`model_id`	`str`	Yes	—	Model ID from commit step
`weights_url`	`str`	Yes	—	URL of encrypted weights
`encrypted_weights`	`bytes`	Yes	—	Encrypted weights (for checksum)
`decryption_key`	`str`	Yes	—	Hex AES-256 decryption key
`embedding`	`list[float]`	Yes	—	Model embedding vector

submit_data

Submit data to fill a target.

async def submit_data(
    signer: Keypair,
    target_id: str,
    data: bytes,
    data_url: str,
    model_id: str,
    embedding: list[float],
    distance_score: float,
) -> None

Parameter	Type	Required	Default	Description
`signer`	`Keypair`	Yes	—	Keypair to sign
`target_id`	`str`	Yes	—	Target to submit to
`data`	`bytes`	Yes	—	Raw submission data
`data_url`	`str`	Yes	—	URL where data is hosted
`model_id`	`str`	Yes	—	Model used for scoring
`embedding`	`list[float]`	Yes	—	Data embedding vector
`distance_score`	`float`	Yes	—	Distance score (must be ≤ target threshold)

claim_rewards

Claim rewards from a filled target.

async def claim_rewards(
    signer: Keypair,
    target_id: str,
) -> None

Parameter	Type	Required	Default	Description
`signer`	`Keypair`	Yes	—	Keypair to sign
`target_id`	`str`	Yes	—	Target to claim from