SAService ArchitectDocumentation

/

DocumentationPython DSL

Reference

Python DSL

Reference for typed Service Architect objects, browser-safe topology authoring, canonical YAML, and generated project downloads.

Getting Started

Python DSL overviewA typed authoring layer for executable architecture: model meaningful stages and contracts, while implementing their business behavior in the generated service.Python objects -> Service Architect YAML -> generated projectInstallation and commandsInstall the package and use its CLI for validation, YAML output, and reverse generation.sa-dsl inspect | validate | export | generate | importIDE pluginsExplore a typed Python architecture graph in VS Code or JetBrains IDEs, navigate to source, and generate service code without replacing the authoring project.Modular project layoutSplit a large topology into importable modules instead of maintaining one monolithic Python file.<project>/project + services + pipelines + connectors + endpoints + typesGitHub source and examplesOpen the implementation, canonical modular example, authentication template, and executable tests on GitHub.github.com/gorundebug/sa-python-dsl

Authoring API

Project APIThe root registry and entry point for every topology entity and output operation.Project(name, *, module_version=None, repo_path=None, properties={})Typed factoriesConcrete methods constrain configuration at the Python call site instead of accepting a free-form type field.pipeline.map(...) | http.post(...) | project.int_type(...)Stream connections and linksBuild graph relationships directly between Stream objects and add persisted delivery settings only when they differ from service defaults.source >> target | target << source | source.priority_task_pool_call(target, ...)Declarative authoring restrictionsKeep Python files as a deterministic, reviewable description of the graph rather than a general application program.deterministic declarations only

YAML and Designer API

Validation and YAML outputValidate the composed object graph and serialize symbolic references into the canonical YAML contract.project.validate() | project.to_yaml()Generate Python from YAMLReverse an existing Service Architect YAML document into a modular, importable Python project.yaml_to_python_project(source, output_dir)Designer API JSONConvert symbolic YAML into the flat JSON model sent by the designer to the code-generation API.yaml_to_api_document(source)

Designer Workflow

Python DSL in DesignerEdit a complete modular Python topology project directly in the browser without a Python server.Project page -> Python DSLApply, revisions, and conflictsApply uses a conflict-aware merge so Graph and Python edits do not silently overwrite one another.Python base + current graph + edited PythonRound-trip guarantees and limitsRound-trip preserves the architecture model, but it does not preserve arbitrary Python source structure.YAML -> Python -> YAML

Code Generation API

API key authenticationAuthenticate scripts, CI, Codex, and MCP with a revocable key created by the signed-in Service Architect user.SERVICE_ARCHITECT_API_KEY=sa_live_<key-id>_<secret>Generate and download project codeSend the complete topology to the authorized generation endpoint and receive a validated ZIP archive.project.generate_code() -> GeneratedProjectArchiveClient reuse and errorsReuse authentication across requests and handle network, API, payload, base64, and archive failures explicitly.ServiceArchitectClient | AuthenticationError | CodeGenerationError

Codex and MCP

Project manifestDeclare the trusted Python entrypoint, canonical YAML output, and generation targets in one discoverable project contract..service-architect/project.yamlCodex plugin and MCP toolsGive Codex a typed editing workflow and stable inspect, validate, export, generate, and import operations.service-architect@service-architect

API: Core Objects

ProjectThe root object that owns every declaration and output operation.Project(name, *, module_version=None, repo_path=None, properties={})Package, Module, Function, and InitializerGroupTyped ownership and generated callback metadata passed to type, endpoint, and stream factories.Package | Module | Function | InitializerGroupPool, Service, and PipelineExecution capacity, deployment boundary, and stream namespace objects.project.pool() | project.service() | service.pipeline()ComponentA service-owned definition of repeated graph fragments. Register each concrete repetition using existing Stream objects.service.component(name, *, description=None)Stream and Link objectsRuntime graph nodes and optional persisted execution metadata for an existing edge.source >> target | target << source | source.task_pool_call(target, pool=...)

API: Types

Primitive type factoriesCreate named definitions over built-in DataType contracts without passing a string discriminator.project.<primitive>_type(name, ...)Struct, array, map, and custom typesCompose container types and target-language or schema-defined contracts from registered type objects.struct_type() | array_type() | map_type() | custom_type()

API: Streams

Pipeline.substream()Declare a callable business graph with an input argument and a result-producing stream in the same service.pipeline.substream(name, *, value_type, source=None, appearance=None)Input and SinkBind a stream graph to connector endpoints for inbound and outbound transport.pipeline.input() | pipeline.sink()Map, Filter, Process, Delay, and expansionSingle-input operators that transform, select, execute, delay, expand, or key messages.map | filter | process | delay | flat_map | flat_map_iterable | key_byJoin, Merge, Split, Case, and control streamsMulti-input, branching, cycle, condition, and error-flow operators.join | multi_join | merge | split | case | cycle_link | error | when

API: Connectors

Project connector factoriesCreate transport-specific Connector subclasses with language adapter defaults selected by the DSL.project.http_connector() | grpc_connector() | kafka_connector() | ...HTTP, gRPC, Kafka, and Custom endpointsCreate concrete endpoints whose parameters match their connector transport.get() | post() | unary_method() | streaming methods | topic() | endpoint()Cron and Temporal endpointsCreate local Cron callbacks and Temporal Activity or Workflow endpoints with typed scheduling and timeout options.schedule() | activity() | workflow()

API: Utilities and Clients

Enums and sentinelsUse exported enum members and sentinel objects instead of reproducing serialized strings.Golang() | DataConnectorImplementation.IBM_SARAMA | LOCAL_MODULEYAML conversion APIConvert canonical YAML either into Python source modules or into the flat designer/API JSON model.yaml_to_python_project() | yaml_to_api_document()ServiceArchitectClient and archive APILow-level reusable API for authenticated generation and validated ZIP handling.ServiceArchitectClient.from_env().generate_code(project)