SAService ArchitectDocumentation

/

DocumentationPython DSL

Reference

Python DSL

Author Service Architect topologies with typed Python objects, round-trip YAML, authenticate with Cognito, and download generated 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.pip install -e . | sa-dsl check | sa-dsl build | sa-dsl importModular project layoutSplit a large topology into importable modules instead of maintaining one monolithic Python file.<project>/project + services + pipelines + connectors + endpoints + types

Authoring API

Project APIThe root registry and entry point for every topology entity and output operation.Project(name, module_version, repo_path)Typed factoriesConcrete methods constrain configuration at the Python call site instead of accepting a free-form type field.pipeline.map(...) | connector.route(...) | 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.link(target, ...)

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)

Code Generation API

Cognito authenticationAuthenticate with the same Cognito user pool and SRP flow used by the designer without storing an ID token.ServiceArchitectClient.from_env()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

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()Stream and Link objectsRuntime graph nodes and optional persisted execution metadata for an existing edge.source >> target | target << source | source.link(target, ...)

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 | 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.route() | method() | 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.ProgrammingLanguage.GO | CallSemantics.TASK_POOL | 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)