Reference
Python DSL
Author Service Architect topologies with typed Python, edit them in Designer, export canonical YAML, and generate runtime projects.
Getting Started
Python DSL overviewA typed authoring layer for the same topology consumed by the designer and ServiceGen.
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 | importModular 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-dslYAML 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 -> YAMLCode 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 | CodeGenerationErrorCodex 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-architectAPI: 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()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
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 | whenAPI: 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)