Serve documentation from the operator UI

2026-08-02 15:50:07 +03:00
parent 284aef5d6f
commit f20cc7fe00
72 changed files with 3509 additions and 698 deletions
@@ -0,0 +1,45 @@
+# API reference
+
+This section is **generated from docstrings** by
+[`mkdocstrings`](https://mkdocstrings.github.io) — it is the complete public
+API surface of `scimesh.sdk`. Markdown pages in `api/` are thin wrappers
+(`::: scimesh.sdk.<module>`) and must not be hand-edited; change the code and
+rebuild with `make docs`.
+
+All value objects are frozen, recursively immutable, JSON-safe, canonically
+serialized, and strict about unknown fields. Constructing them performs
+full validation; invalid input raises `ValueError`.
+
+## Module map
+
+| Page | Module | Contents |
+| --- | --- | --- |
+| [Artifacts and ports](sdk-artifacts.md) | `scimesh.sdk.artifacts` | `ArtifactSchema`, `PortSpec`, `ArtifactRef`, `ArtifactCollection`, `OutputManifest`, `Provenance` |
+| [Batch scaffold](sdk-batch.md) | `scimesh.sdk.batch` | `MapReduceWorkload`, `concatenate_partial_tables` |
+| [Conformance runtime](sdk-conformance.md) | `scimesh.sdk.conformance` | `LocalArtifactStore`, `LocalCoreBatchExecutor`, scoped contexts, round-trip helper |
+| [Execution profiles](sdk-execution.md) | `scimesh.sdk.execution` | `ExecutionProfile`, `RetryPolicy`, `CheckpointPolicy`, `FailureReport` |
+| [Identities](sdk-identity.md) | `scimesh.sdk.identity` | `WorkloadId`, `VersionRange`, `SchemaRef`, `ComponentRef`, `FeatureRequirement` |
+| [Package integrity](sdk-integrity.md) | `scimesh.sdk.integrity` | `installed_distribution_digest` |
+| [Manifests](sdk-manifest.md) | `scimesh.sdk.manifest` | `WorkloadManifest`, `PackageSpec`, `EnvironmentSpec`, `VerifierSpec`, `WorkloadLimits`, trust/determinism enums |
+| [Plans and tasks](sdk-plans.md) | `scimesh.sdk.plans` | `JobRequest`, `ValidatedJob`, `TaskSpec`, `WorkflowPlan`, `ExpansionManifest` |
+| [Handler protocols](sdk-protocols.md) | `scimesh.sdk.protocols` | `Planner`, `Runner`, `Reducer`, `Verifier`, contexts, catalog/sink |
+| [Registry](sdk-registry.md) | `scimesh.sdk.registry` | `WorkloadRegistry`, `WorkloadDefinition`, `AllowedPackage`, discovery |
+| [Resources](sdk-resources.md) | `scimesh.sdk.resources` | `ResourceRequirements`, `ResourceInventory`, `ResourcePool`, accelerators |
+| [Runtime negotiation](sdk-runtime.md) | `scimesh.sdk.runtime` | `RuntimeCapabilities`, `negotiate_manifest`, `CompatibilityError` |
+| [Parameter schemas](sdk-schema.md) | `scimesh.sdk.schema` | Bounded JSON Schema subset |
+| [Verification](sdk-verification.md) | `scimesh.sdk.verification` | Verifiers, decisions, bindings, candidate envelopes |
+| [Workflow DAGs](sdk-workflow.md) | `scimesh.sdk.workflow` | `WorkflowSpec`, `StageSpec`, `ArtifactEdge`, advanced declarations |
+
+## Reading the generated pages
+
+- **Classes** show their full signature, validation rules, and public
+  methods; properties are listed with their type.
+- **Module-level functions** (for example `negotiate_manifest`) document
+  their exact contract and failure modes.
+- Cross-references to other SDK symbols link automatically.
+
+To keep the reference correct:
+
+- write docstrings in **Google style** (`Args:` / `Returns:` / `Raises:`);
+- document validation failures and fail-closed behavior;
+- rebuild with `make docs` after any docstring change.
@@ -0,0 +1,8 @@
+# Artifacts and ports
+
+Typed artifact schemas, port declarations, immutable artifact references and
+collections, output manifests, and provenance.
+
+::: scimesh.sdk.artifacts
+    options:
+      show_root_heading: false
@@ -0,0 +1,9 @@
+# Batch scaffold
+
+The primary authoring surface for `core-batch-v1`: `MapReduceWorkload` and
+the default partial-concatenation helper. See the
+[authoring guide](../sdk/authoring-workloads.md) for a full walkthrough.
+
+::: scimesh.sdk.batch
+    options:
+      show_root_heading: false
@@ -0,0 +1,8 @@
+# Conformance runtime
+
+The trusted, in-process correctness harness: content-addressed artifact
+store, scoped catalog/sink contexts, and `LocalCoreBatchExecutor`.
+
+::: scimesh.sdk.conformance
+    options:
+      show_root_heading: false
@@ -0,0 +1,7 @@
+# Execution profiles
+
+Execution, retry, checkpoint, and failure declarations.
+
+::: scimesh.sdk.execution
+    options:
+      show_root_heading: false
@@ -0,0 +1,8 @@
+# Identities and versions
+
+Versioned identities used across the SDK: workload ids, version ranges,
+schema and component references, and feature requirements.
+
+::: scimesh.sdk.identity
+    options:
+      show_root_heading: false
@@ -0,0 +1,7 @@
+# Package integrity
+
+Content pinning of installed distributions for allowlisted discovery.
+
+::: scimesh.sdk.integrity
+    options:
+      show_root_heading: false
@@ -0,0 +1,7 @@
+# Manifests
+
+The installed-package manifest and cross-component compatibility contract.
+
+::: scimesh.sdk.manifest
+    options:
+      show_root_heading: false
@@ -0,0 +1,8 @@
+# Plans and tasks
+
+Strict job, task, and workflow-plan value objects, plus dynamic expansion
+manifests.
+
+::: scimesh.sdk.plans
+    options:
+      show_root_heading: false
@@ -0,0 +1,8 @@
+# Handler protocols
+
+Author-facing contracts for planners, runners, reducers, verifiers, and the
+bridge-owned catalog/sink/cancellation contexts.
+
+::: scimesh.sdk.protocols
+    options:
+      show_root_heading: false
@@ -0,0 +1,8 @@
+# Registry and discovery
+
+Explicit, digest-pinned workload package registry and safe installed
+discovery.
+
+::: scimesh.sdk.registry
+    options:
+      show_root_heading: false
@@ -0,0 +1,8 @@
+# Resources
+
+Resource requirements, host inventory, atomic local reservation, and
+accelerator declarations.
+
+::: scimesh.sdk.resources
+    options:
+      show_root_heading: false
@@ -0,0 +1,7 @@
+# Runtime negotiation
+
+Fail-closed SDK/profile/feature/resource compatibility negotiation.
+
+::: scimesh.sdk.runtime
+    options:
+      show_root_heading: false
@@ -0,0 +1,7 @@
+# Parameter schemas
+
+The bounded JSON Schema subset used for public workload parameters.
+
+::: scimesh.sdk.schema
+    options:
+      show_root_heading: false
@@ -0,0 +1,8 @@
+# Verification
+
+Verifier primitives, decisions, coordinator bindings, and candidate
+envelopes for quorum acceptance.
+
+::: scimesh.sdk.verification
+    options:
+      show_root_heading: false
@@ -0,0 +1,8 @@
+# Workflow DAGs
+
+Versioned workflow graphs, stage declarations, artifact edges, and bounded
+advanced-stage declarations (loops, streams, gangs, side effects).
+
+::: scimesh.sdk.workflow
+    options:
+      show_root_heading: false