Author a blueprint

This reference describes the blueprint source format accepted by the SDK and its packaged JSON Schemas. It covers development folders, installed folders, catalog packages, generated blueprints, and ZIP distributions. Core's generated execution manifest is documented separately in Job Bundle Format.

The format identifier is https://mirrorneuron.io/schemas/blueprint/v1/manifest.schema.json. The blueprint's version is its semantic release version. There is no authored apiVersion, kind, manifest_version, profile, or raw runtime-manifest override in the core document.

Package layout

legal_assistant/
  manifest.json
  workflow.json
  execution.json
  contracts.json
  dependencies.json
  config/default.json
  config/overwrite.json
  extensions/llm.json
  extensions/product.json
  payloads/
  LICENSE.md
  TERM.md

dependencies.json, extensions, legal documents, and the local overwrite file are optional. A package with no code assets does not need payloads/. Required roles are referenced explicitly; their filenames can differ from these examples.

{
  "$schema": "https://mirrorneuron.io/schemas/blueprint/v1/manifest.schema.json",
  "id": "legal_assistant",
  "name": "Legal Assistant",
  "version": "1.0.0",
  "description": "Review legal documents and prepare a review packet.",
  "license": "LICENSE.md",
  "terms": "TERM.md",
  "workflow": "workflow.json",
  "execution": "execution.json",
  "contracts": "contracts.json",
  "config": "config/default.json",
  "dependencies": "dependencies.json",
  "extensions": {
    "mn.llm": {"file": "extensions/llm.json", "required": true},
    "mn.product": {"file": "extensions/product.json", "required": false}
  }
}

All references are ordinary package-relative POSIX paths. Documents have fixed responsibilities, not arbitrary include or override semantics.

The SDK ships Draft 2020-12 schemas for each role and known extension. Canonical schema identifiers resolve against the SDK's local registry without fetching schemas from the network. Unknown core fields, duplicate JSON properties, invalid release versions, missing documents, and unsupported schema identifiers are errors.

Dependency versions

Declare SDK distributions under packages and reusable workers under skills or agents in dependencies.json. Every declared dependency needs a version. Package records use type: "pip", source: "gar", and the distribution name.

Versions accept exact releases (1.3.47), PEP 440 ranges (>=1.3.5,<2.0), compatible releases (~=1.3.5), and trailing wildcards (1.3.x or 1.3.*). Empty values, bare *, URLs, environment markers, caret ranges, and || are rejected. Authored constraints survive compilation; binary preparation resolves an available compatible artifact. Exact pins provide stronger reproducibility than ranges.

With MN_USE_LOCAL_SKILLS=1, source development resolves matching local distribution identities regardless of their declared release range. With MN_USE_LOCAL_SKILLS=0, binary preparation preserves constraints and does not automatically select bundled source. Unversioned skills fail preparation; there is no SDK-version fallback for a skill.

Execution modes

execution.mode is required:

• compiled: logical workflows, reusable worker declarations, and Python StepSpec definitions are compiled into a physical agent graph.
• explicit: a native or custom physical graph is declared directly through execution agents and runtime bindings.

Both modes have the same package structure and use the same loader and submission preparation. execution.type specifies batch or service execution. Shared step settings belong in workflow.defaults.step; shared workers belong in execution.defaults.worker and worker groups. Defaults are applied deterministically by the SDK's format-v1 compiler.

A logical workflow uses either needs on its steps or an explicit edges list. An edge can carry its event or condition declaration. Combining the two forms is rejected. Step IDs must be unique, referenced steps must exist, and logical dependencies must be acyclic. Bounded loops and dynamic templates remain explicit workflow capabilities.

StepSpec modules define contracts and collaboration. Agent handlers own work, and blueprint payloads own domain policy. The SDK imports StepSpec modules only during requested compilation, in subprocesses with a ten-second deadline. Missing dependencies fail compilation; they never generate substitute nodes.

Extensions

Each extension document declares its own canonical $schema. Manifest extension registrations name the document and state whether support is required.

Known runtime features are handled by the SDK. An unknown required extension fails compilation. Unknown optional descriptive extensions remain in the snapshot and exported package without being executed. Adding a runtime feature requires a handler and a schema; adding fields to the core document is not an extension mechanism.

Loading and configuration

The public SDK stages are:

read_blueprint → BlueprintPackage
resolve_config → ResolvedConfiguration
compile_blueprint → CompiledBlueprint
plan_submission → SubmissionPlan
prepare_submission → PreparedSubmission
submit → commit or reconcile

read_blueprint validates and snapshots a folder. open_blueprint is a context manager that accepts a folder or ZIP; extraction is the only transport-specific stage. A package records each document's source path, file content hashes, executable permissions, and a content fingerprint. Document access returns copies, so callers cannot mutate the snapshot.

from mn_sdk.blueprints import open_blueprint, resolve_config, compile_blueprint

with open_blueprint("./legal_assistant") as package:
    configuration = resolve_config(package, {"execution": {"quick_test": True}})
    compiled = compile_blueprint(package, configuration)
    print(package.manifest["id"], compiled.fingerprint)

Configuration resolves in this order:

1. SDK projections of declared feature descriptors.
2. The referenced default configuration document.
3. config/overwrite.json, when present in the package snapshot.
4. Invocation overrides.

The resolver provides identity, model, retrieval, resource, adapter, and human-control settings through one resolved configuration. There is no authored config.manifest_defaults path projection list. Worker code uses the SDK runtime configuration and resolved descriptor accessors. Launch identity, environment, and secrets are separate launch inputs; adapters must not mutate process-global environment variables to launch a job.

Compilation fingerprints include the package fingerprint, resolved configuration, and compiled graph. Source changes between reading and compilation are rejected. Fingerprints are deterministic across relocation and ZIP transport, and include referenced documents and payload content.

Catalogs

index.json is only an ordered inventory of published package paths:

["legal_assistant", "purchasing_manager", "research_assistant"]

read_catalog validates those folders and derives descriptive records from their manifests and extensions. It does not import blueprint Python, install dependencies, prepare models, restore databases, or provision services. A folder absent from the index remains a valid unpublished package. Duplicate paths and duplicate blueprint identities are errors.

Submission and ownership

CLI, REST, and Python launches share SDK configuration, compiler, dependency preparation, payload assembly, and native resource contracts. Workers receive one complete resolved descriptor at runtime/manifest.json, including role documents and resolved configuration. This is a generated worker artifact, distinct from the package's small authored manifest.

Preparation uses a unique submission identity and tracks native resource ownership. Confirmed preparation failure rolls back resources acquired by that preparation. Cancellation is included. A submission timeout or malformed acknowledgement is not proof that Core rejected the definition. Reconciliation compares the submission identity against Core's authoritative ownership projection before a retry or cleanup. Uncertain outcomes preserve resources.

Persistent job data belongs to the durable job. Input staging and execution identifiers belong to individual launches. Replacement and cleanup must retain these boundaries. Secret injection and monitoring redaction occur at the submission boundary; source migration does not rewrite deployed jobs or run history.

Paths, transport, and export

Folders and extracted ZIPs use the same package path validator. Absolute document paths, traversal, symlinks, duplicate destinations, and conflicting document-role destinations are rejected. ZIP extraction preflights its members before writing, with limits of 32 GiB and 100,000 entries. Folder snapshots apply corresponding content limits. Large assets are hashed and exported in chunks.

export_blueprint(package, destination) exports the complete portable file snapshot, including referenced documents, declared assets, code, configuration, and legal files. It excludes development caches and checks for changed files. Export outside the source package. Executable bits survive export and reimport. External dependencies remain explicitly declared; vendoring is optional.

Validate and try the package

From the directory containing your blueprint, replace ./my-blueprint with its path:

mn blueprint validate ./my-blueprint
mn blueprint doctor ./my-blueprint

Fix missing documents, invalid fields, dependency declarations, and prerequisites before launch. Review executable payloads and external actions, then follow Quickstart to run sample inputs, inspect outputs, and cancel unfinished work.

The schema format and installed SDK release are separate version numbers. Use compatible CLI, API, SDK, and catalog releases; check the installed SDK's packaged schemas when a package is rejected.