Payloads service¶

`consortium.server.services.payloads_service` ¶

`PayloadsService(events_service, repository_service, agent_templates_service)` ¶

`repository_directory_path = repository_service.repository_directory_path` `instance-attribute` ¶

`load_repository_metadata()` ¶

See RepositoryService.load_repository_metadata.

`save_repository_metadata()` ¶

See RepositoryService.save_repository_metadata.

`reserve_resource_id()` ¶

Generates and reserves a resource ID to be claimed later during payload creation.

Reservations are required when the caller needs to know the resource ID before the payload file or directory has been created (e.g., to name the file after the ID). The reserved ID must be provided as resource_id to create_payload_file or create_payload_directory.

Returns:

Type	Description
`UUID`	The reserved resource ID.

`create_payload_file(agent_template_id, build_parameters, content, payload_data=None, resource_id=None, name=None, description='')` `async` ¶

Creates a file-based payload and associates it with an agent template.

Build parameters are validated against the agent template before creating the resource. If resource_id is provided it must have been previously reserved via reserve_resource_id. Emits a PAYLOAD_CREATED event.

Parameters:

Name	Type	Description	Default
`agent_template_id`	`str \| UUID`	The ID of the agent template to associate with the payload.	required
`build_parameters`	`dict[str, Any]`	Parameters used to build the agent generator from the template (validated against the template).	required
`content`	`str \| bytes \| TextIO \| BinaryIO`	The file content to write to the repository.	required
`payload_data`	`dict[str, Any] \| None`	Arbitrary metadata attached to the payload. When `None`, no extra metadata is stored.	`None`
`resource_id`	`str \| UUID \| None`	A previously reserved ID to assign to this payload. When `None`, a new ID is generated automatically.	`None`
`name`	`str \| None`	A human-readable name for the payload file. When `None`, the resource UUID is used.	`None`
`description`	`str`	An optional description for the payload.	`''`

Returns:

Type	Description
`Payload`	The created payload.

Raises:

Type	Description
`AgentTemplateIDNotFoundError`	If no agent template with the given ID exists.
`MissingRequiredAgentTemplateOptionError`	If a required option is absent from `build_parameters`.
`AgentTemplateOptionNotFoundError`	If `build_parameters` contains an unknown option name.
`AgentTemplateOptionValueValidationError`	If an option value in `build_parameters` fails type or constraint validation.
`AgentTemplateValidatingFunctionError`	If the agent template's validating function rejects the resolved options.
`ResourceIDReservationNotFoundError`	If `resource_id` is provided but has no corresponding reservation.
`RepositoryResourceFileSystemError`	If the file cannot be written to disk.
`RepositoryMetadataFileSystemError`	If the payload metadata cannot be written to disk after the file is written.
`UnicodeDecodeError`	If `content` is a text stream carrying content that cannot be decoded.

`add_payload_file(agent_template_id, build_parameters, path, payload_data=None, resource_id=None, name=None, description='', copy=False)` `async` ¶

Registers an existing file on disk as a file-based payload.

Unlike create_payload_file, no new file is written. The file at path is moved (or copied when copy=True) into the repository. Build parameters are validated against the agent template before registration. If resource_id is provided it must have been previously reserved via reserve_resource_id. Emits a PAYLOAD_CREATED event.

Parameters:

Name	Type	Description	Default
`agent_template_id`	`str \| UUID`	The ID of the agent template to associate with the payload.	required
`build_parameters`	`dict[str, Any]`	Parameters used to build the agent generator from the template (validated against the template).	required
`path`	`Path \| str`	Path to the existing file to register.	required
`payload_data`	`dict[str, Any] \| None`	Arbitrary metadata attached to the payload. When `None`, no extra metadata is stored.	`None`
`resource_id`	`str \| UUID \| None`	A previously reserved ID to assign to this payload. When `None`, a new ID is generated.	`None`
`name`	`str \| None`	A human-readable name for the payload file. When `None`, the original filename is used.	`None`
`description`	`str`	An optional description for the payload.	`''`
`copy`	`bool`	When `False` (default) the source file is moved into the repository. When `True` the source file is copied and the original is left in place.	`False`

Returns:

Type	Description
`Payload`	The registered payload.

Raises:

Type	Description
`AgentTemplateIDNotFoundError`	If no agent template with the given ID exists.
`MissingRequiredAgentTemplateOptionError`	If a required option is absent from `build_parameters`.
`AgentTemplateOptionNotFoundError`	If `build_parameters` contains an unknown option name.
`AgentTemplateOptionValueValidationError`	If an option value in `build_parameters` fails type or constraint validation.
`AgentTemplateValidatingFunctionError`	If the agent template's validating function rejects the resolved options.
`ResourceIDReservationNotFoundError`	If `resource_id` is provided but has no corresponding reservation.
`RepositoryResourceFileSystemError`	If no file exists at `path`, or the file cannot be moved or copied into the repository.
`RepositoryMetadataFileSystemError`	If the payload metadata cannot be written to disk afterwards.

`create_payload_directory(agent_template_id, build_parameters, content, payload_data=None, resource_id=None, archive_file_format='zip', name=None, description='')` `async` ¶

Creates a directory-based payload by extracting an archive and associating it with an agent template.

Build parameters are validated against the agent template before creating the resource. If resource_id is provided it must have been previously reserved via reserve_resource_id. Emits a PAYLOAD_CREATED event.

Parameters:

Name	Type	Description	Default
`agent_template_id`	`str \| UUID`	The ID of the agent template to associate with the payload.	required
`build_parameters`	`dict[str, Any]`	Parameters used to build the agent generator from the template (validated against the template).	required
`content`	`bytes \| BinaryIO`	The archive content to extract into the repository directory.	required
`payload_data`	`dict[str, Any] \| None`	Arbitrary metadata attached to the payload. When `None`, no extra metadata is stored.	`None`
`resource_id`	`str \| UUID \| None`	A previously reserved ID to assign to this payload. When `None`, a new ID is generated automatically.	`None`
`archive_file_format`	`Literal['zip', 'tar', 'gztar', 'bztar', 'xztar']`	The format of the archive to extract. Defaults to `"zip"`.	`'zip'`
`name`	`str \| None`	A human-readable name for the payload directory. When `None`, the resource UUID is used.	`None`
`description`	`str`	An optional description for the payload.	`''`

Returns:

Type	Description
`Payload`	The created payload.

Raises:

Type	Description
`AgentTemplateIDNotFoundError`	If no agent template with the given ID exists.
`MissingRequiredAgentTemplateOptionError`	If a required option is absent from `build_parameters`.
`AgentTemplateOptionNotFoundError`	If `build_parameters` contains an unknown option name.
`AgentTemplateOptionValueValidationError`	If an option value in `build_parameters` fails type or constraint validation.
`AgentTemplateValidatingFunctionError`	If the agent template's validating function rejects the resolved options.
`ResourceIDReservationNotFoundError`	If `resource_id` is provided but has no corresponding reservation.
`InvalidRepositoryDirectoryArchiveFileFormatError`	If `content` cannot be unpacked as `archive_file_format`, or if `archive_file_format` is not set.
`RepositoryResourceFileSystemError`	If the directory cannot be created or the archive cannot be unpacked into it.
`RepositoryMetadataFileSystemError`	If the payload metadata cannot be written to disk after the directory is created.

`add_payload_directory(agent_template_id, build_parameters, path, payload_data=None, resource_id=None, name=None, description='', copy=False)` `async` ¶

Registers an existing directory on disk as a directory-based payload.

Unlike create_payload_directory, no archive is extracted and no new directory is created. The directory at path is moved (or copied when copy=True) into the repository. Build parameters are validated against the agent template before registration. If resource_id is provided it must have been previously reserved via reserve_resource_id. Emits a PAYLOAD_CREATED event.

Parameters:

Name	Type	Description	Default
`agent_template_id`	`str \| UUID`	The ID of the agent template to associate with the payload.	required
`build_parameters`	`dict[str, Any]`	Parameters used to build the agent generator from the template (validated against the template).	required
`path`	`Path \| str`	Path to the existing directory to register.	required
`payload_data`	`dict[str, Any] \| None`	Arbitrary metadata attached to the payload. When `None`, no extra metadata is stored.	`None`
`resource_id`	`str \| UUID \| None`	A previously reserved ID to assign to this payload. When `None`, a new ID is generated.	`None`
`name`	`str \| None`	A human-readable name for the payload directory. When `None`, the original directory name is used.	`None`
`description`	`str`	An optional description for the payload.	`''`
`copy`	`bool`	When `False` (default) the source directory is moved into the repository. When `True` the source directory is copied and the original is left in place.	`False`

Returns:

Type	Description
`Payload`	The registered payload.

Raises:

Type	Description
`AgentTemplateIDNotFoundError`	If no agent template with the given ID exists.
`MissingRequiredAgentTemplateOptionError`	If a required option is absent from `build_parameters`.
`AgentTemplateOptionNotFoundError`	If `build_parameters` contains an unknown option name.
`AgentTemplateOptionValueValidationError`	If an option value in `build_parameters` fails type or constraint validation.
`AgentTemplateValidatingFunctionError`	If the agent template's validating function rejects the resolved options.
`ResourceIDReservationNotFoundError`	If `resource_id` is provided but has no corresponding reservation.
`RepositoryResourceFileSystemError`	If no directory exists at `path`, or the directory or any file within it cannot be moved or copied into the repository.
`RepositoryMetadataFileSystemError`	If the payload metadata cannot be written to disk afterwards.

`update_payload_by_resource_id(resource_id, name=None, description=None, agent_template_id=None, build_parameters=None, payload_data=None)` `async` ¶

Updates a payload's mutable metadata.

name and description are updated in place when provided. The payload's stored data is only rebuilt when agent_template_id is passed, mirroring the parameters of the payload creation methods: the agent template is resolved and the supplied build_parameters are validated against it exactly as they would be on creation before the new metadata is recorded. When agent_template_id is omitted the existing data is left untouched. Emits a PAYLOAD_UPDATED event.

Parameters:

Name	Type	Description	Default
`resource_id`	`str \| UUID`	The ID of the payload to update.	required
`name`	`str \| None`	A new human-readable name for the payload. When `None`, the existing name is preserved.	`None`
`description`	`str \| None`	A new description for the payload. When `None`, the existing description is preserved.	`None`
`agent_template_id`	`str \| UUID \| None`	When provided, rebuilds the payload's `data` from this agent template. When omitted, the payload's existing data is left unchanged.	`None`
`build_parameters`	`dict[str, Any] \| None`	Parameters used to build the agent generator from the template (validated against the template). Only used, and defaulted to an empty mapping, when `agent_template_id` is provided.	`None`
`payload_data`	`dict[str, Any] \| None`	Arbitrary metadata attached to the payload. Only used when `agent_template_id` is provided.	`None`

Returns:

Type	Description
`Payload`	The updated payload.

Raises:

Type	Description
`ResourceNotFoundError`	If no payload with the given ID exists.
`RepositoryMetadataFileSystemError`	If the updated metadata cannot be written to disk.
`AgentTemplateIDNotFoundError`	If `agent_template_id` is provided but no agent template with that ID exists.
`MissingRequiredAgentTemplateOptionError`	If `agent_template_id` is provided and a required option is absent from `build_parameters`.
`AgentTemplateOptionNotFoundError`	If `agent_template_id` is provided and `build_parameters` contains an unknown option name.
`AgentTemplateOptionValueValidationError`	If `agent_template_id` is provided and an option value in `build_parameters` fails type or constraint validation.
`AgentTemplateValidatingFunctionError`	If `agent_template_id` is provided and the agent template's validating function rejects the resolved options.

`delete_payload_by_resource_id(resource_id)` `async` ¶

Deletes a payload from disk and the repository.

A payload is "just" a repository resource whose data field carries the payload metadata, so deleting the resource removes the payload in full. The payload's JSON is snapshotted before removal so it can be carried on the emitted PAYLOAD_DELETED event, then the resource is deleted from disk and deregistered.

Parameters:

Name	Type	Description	Default
`resource_id`	`str \| UUID`	The ID of the payload to delete.	required

A payload whose file or directory is already missing from the repository directory is deleted successfully: the record is deregistered and the event is still emitted.

Raises:

Type	Description
`ResourceNotFoundError`	If no payload with the given ID exists.
`RepositoryResourceFileSystemError`	If the payload's file or directory exists on disk but cannot be deleted.
`RepositoryMetadataFileSystemError`	If the metadata file cannot be written to disk after deletion.

`get_payload_by_resource_id(resource_id)` ¶

Returns a payload by its ID.

Parameters:

Name	Type	Description	Default
`resource_id`	`str \| UUID`	The ID of the payload to retrieve.	required

Returns:

Type	Description
`Payload`	The requested payload.

Raises:

Type	Description
`ResourceNotFoundError`	If no payload with the given ID exists.

`get_all_payloads()` ¶

Returns every payload currently tracked by the payloads service.

Returns:

Type	Description
`list[Payload]`	A list of all payloads, covering both file and directory payloads, each wrapping its repository resource. Empty if no payloads exist.

Payloads service¶

consortium.server.services.payloads_service ¶