Developers

SDK & API Documentation

Build, seal, and federate studios with the SCPN Studio Platform SDK.

The SCPN Studio Platform SDK is the Python toolkit behind every Anulum studio. It gives you typed manifests, evidence bundles, seal ceremonies, and federation contracts so your scientific computing surface stays reproducible and independently verifiable.

This page is the public reference for the two core schemas — the capability manifest (schema A) and the evidence bundle (schema B) — plus the verb attribute contract and the key platform modules you will call from your own studio code.

SDK surface

Five modules, one contract

The platform SDK is organised around the operations every scientific studio needs: emit evidence, declare a manifest, define verbs, manage identity, and run jobs. Each module is typed, sealed, and checked by the Hub before federation.

Evidence

Build studio.*.v1 bundles with PROV-O graphs, claim boundaries, evidence kinds, and empirical levels.

Manifest

Declare schema-A capability manifests: studio identity, verbs, evidence types, backends, and optional UI modules.

Verbs

Tag each verb with safety tier, side-effect class, timing, fidelity, and the evidence schema it produces.

Identity

Opaque principals and tenant-scoped profiles keep authentication local-first and fail-closed.

Jobs

Immutable job lifecycles and resource budgets reject unprojectable work before it reaches a backend.

Open interactive API docs → Browse repositories on GitHub

Quickstart

Six steps from installation to a federated studio.

  1. 1
    Install the platform SDK

    Add scpn-studio-platform to your studio environment (Python 3.11+).

  2. 2
    Scaffold a studio

    Run scpn studio create <studio-name> to generate the manifest, verbs, and project layout.

  3. 3
    Define verbs

    Declare each verb with its safety tier, side-effect class, timing, fidelity, and backends.

  4. 4
    Build the manifest

    Render schema A with CapabilityManifest.to_dict() and pin its content digest.

  5. 5
    Emit evidence

    Produce studio.*.v1 evidence bundles and let the SDK enforce honesty invariants.

  6. 6
    Federate

    Publish the manifest to the Hub, register backends, and join the transparency log.

Capability manifest schema

Schema A — how a studio advertises itself to the Hub.

Field Type Required Description
contract_era string yes Era-versioned network contract, e.g. "v1".
studio string yes Studio identifier, e.g. "scpn-fusion-core".
studio_version string yes The studio's own SemVer version string.
platform_sdk string yes SemVer range of the platform SDK the studio builds on.
content_digest string yes Content-addressed sha256:… digest of the declared surface.
protocol_version string yes SYNAPSE wire protocol version the studio pins.
transport_profile string yes Transport profile the studio requires.
verbs Verb[] yes Advertised capabilities, each with the full attribute contract.
evidence_types string[] yes studio.*.v1 evidence schema names the studio emits.
external_reference_datasets ExternalReferenceDataset[] no External datasets the studio declares a dependency on.
ui_module UiModule no Federated UI module the Hub loads when present.

Evidence bundle schema

Schema B — the aggregate result envelope every verb emits.

Field Type Required Description
schema string yes Concrete schema name, e.g. "studio.transport-run.v1".
prov object yes PROV-O graph: entity, activity, and agent records.
ro_crate_profile string yes RO-Crate profile the bundle conforms to.
scpn_evidence_level integer yes Empirical completeness level, an integer 0–3.
evidence_kind string yes Modality: measured, curated, formally-proven, falsified, etc.
claim_boundary ClaimBoundary yes Lattice status, admission decision, and optional validity domain.
substrate string no Execution substrate: simulator, fpga, asic, etc.
freshness string no How recently the evidence was re-checked at source.
numeric_provenance NumericProvenance no Active backend and optional recovered-dynamics provenance.
formal_certificate FormalCertificate[] no Machine-checked proof certificates; required for formally-proven kind.
cases CaseResult[] no Per-case coverage rows for proof or benchmark results.
physical_contract PhysicalContract no Units, grid, and timestep for a physical result.
recompute_environment RecomputeEnvironment no External toolchain needed to reproduce the result.
verified_citations VerifiedCitation[] no Verified-at-source citations.
attestation Attestation no Signed in-toto attestation, when present.
derived_from DerivedEdge[] no Content-addressed derivation edges.

Verb attribute contract

Every verb declares the attributes the Hub uses to gate federation safely.

name safety_tier side_effect timing fidelity produces backends
simulate research simulated batch first-principles studio.simulate.v1 cpu-reference, fpga-mitigated
prove certified read-only batch analytic studio.prove.v1 symbiyosys
analyse research read-only interactive reduced-order studio.analyse.v1 cpu-reference
synthesise production live-hardware realtime (deadline 1000 µs) ml-surrogate studio.synthesise.v1 asic

API reference

Key modules, classes, and functions in the scpn_studio_platform package.

Evidence

  • EvidenceBundle The studio.*.v1 aggregate result envelope with PROV-O graph, claim boundary, and honesty invariants.
  • ClaimBoundary A claim's lattice status, admission decision, and optional validity domain.
  • EvidenceKind / EvidenceLevel Orthogonal evidence modality and empirical completeness level (0–3).

Manifest

  • CapabilityManifest Schema-A studio advertisement: identity, verbs, evidence types, and federated UI module.
  • content_digest() Content-addressed digest of the declared studio surface.
  • manifest.digest Reproducible, language-agnostic digest computation for manifests.

Verbs

  • Verb A declared capability with safety tier, side-effect class, timing, fidelity, and backends.
  • SafetyTier / SideEffect / Timing Attribute value types the Hub federation layer gates actuation against.
  • VerbProof Proof-method declaration for proof-class verbs (method, engine, version, depth).

Identity

  • Principal Tenant-aware opaque identity: local or multi-tenant profile.
  • ProfileKind Local-first single-owner vs. signed, tenant-scoped identity.
  • can_access_tenant() Per-tenant isolation gate used by the Hub.

Jobs

  • Job Immutable lifecycle state machine for a unit of studio work.
  • JobStatus Pending, running, succeeded, failed, or rejected.
  • ResourceBudget Fail-closed admission gate that rejects unprojectable or over-budget jobs.

Benchmark

  • BenchmarkDatabank Measured values per capability and backend, sealed and logged.
  • dispatch.reconcile() Reconciles declared backend dispatch order against measured data.
  • benchmark.ingest Ingests raw measurements into the studio databank.

Seal

  • PublicationSeal Signed envelope over a published artifact digest.
  • seal.canonical() Canonical JSON serialization used before signing and digesting.
  • seal.verdict Seal verification verdicts and proof-void checks.

Next steps

Open the interactive Commerce API reference, read the platform overview, browse live SCPN Studio projects, or explore the source on GitHub.