Artifacts service¶

`consortium.server.services.artifacts_service` ¶

`ArtifactsService(events_service, repository_service, agents_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()` ¶

Reserves and returns a new resource ID without creating any artifact.

The returned ID can later be passed as resource_id to one of the artifact creation methods to claim it. Reserving an ID up front lets a caller learn the artifact's ID before its file or directory exists on disk (for example to embed the ID inside the content that will be stored).

Returns:

Type	Description
`UUID`	The freshly reserved resource ID, unique across the repository.

`create_artifact_file(content, name=None, description='', resource_id=None, agent_id=None)` `async` ¶

Creates a new artifact file from in-memory or streamed content.

The content is written to a new file on disk in the artifacts repository and an ARTIFACT_CREATED event is emitted. When an agent_id is supplied the producing agent is resolved and recorded against the artifact for attribution.

Parameters:

Name	Type	Description	Default
`content`	`str \| bytes \| TextIO \| BinaryIO`	The content to write into the new artifact file, supplied either directly as text/bytes or as an open text/binary stream to read the content from.	required
`name`	`str \| None`	A human-readable display name for the artifact. When `None`, the artifact's generated UUID is used as its name.	`None`
`description`	`str`	A short human-readable description of the artifact. Defaults to an empty string when omitted.	`''`
`resource_id`	`str \| UUID \| None`	A previously reserved resource ID to claim for this artifact. When `None`, a new ID is generated automatically.	`None`
`agent_id`	`str \| UUID \| None`	The ID of the agent that produced this artifact, recorded for attribution. When `None`, the artifact is stored with no producing agent.	`None`

Returns:

Type	Description
`Artifact`	The newly created artifact file resource.

Raises:

Type	Description
`AgentNotFoundError`	If `agent_id` is provided but no agent with that ID is registered.
`ResourceIDReservationNotFoundError`	If `resource_id` is provided but has no corresponding reservation.
`RepositoryResourceFileSystemError`	If the file cannot be written to disk.
`RepositoryMetadataFileSystemError`	If the artifact 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_artifact_file(path, name=None, description='', resource_id=None, copy=False, agent_id=None)` `async` ¶

Registers an existing file on disk as an artifact.

Unlike create_artifact_file, no new content is written: the file at path is moved (or copied when copy=True) into the artifacts repository, registered as a resource, and an ARTIFACT_CREATED event is emitted. When an agent_id is supplied the producing agent is resolved and recorded for attribution.

Parameters:

Name	Type	Description	Default
`path`	`Path \| str`	Filesystem path to the existing file to ingest as an artifact.	required
`name`	`str \| None`	A human-readable display name for the artifact. When `None`, the original filename is used.	`None`
`description`	`str`	A short human-readable description of the artifact. Defaults to an empty string when omitted.	`''`
`resource_id`	`str \| UUID \| None`	A previously reserved resource ID to claim for this artifact. When `None`, a new ID is generated automatically.	`None`
`copy`	`bool`	When `False` (default) the source file is moved into the repository, leaving nothing at the original path. When `True` the source file is copied and the original is left in place.	`False`
`agent_id`	`str \| UUID \| None`	The ID of the agent that produced this artifact, recorded for attribution. When `None`, the artifact is stored with no producing agent.	`None`

Returns:

Type	Description
`Artifact`	The newly registered artifact file resource.

Raises:

Type	Description
`AgentNotFoundError`	If `agent_id` is provided but no agent with that ID is registered.
`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 artifact metadata cannot be written to disk afterwards.

`create_artifact_directory(content=None, archive_file_format=None, name=None, description='', resource_id=None, agent_id=None)` `async` ¶

Creates a new artifact directory, optionally populated from existing content.

An empty directory is created on disk in the artifacts repository, or, when content is provided, it is populated from that content. How content is interpreted depends on its type: raw bytes and open binary streams are unpacked as archive content using archive_file_format, while a str or pathlib.Path is treated as a path to an existing source directory whose tree is copied in. An ARTIFACT_CREATED event is emitted. When an agent_id is supplied the producing agent is resolved and recorded for attribution.

Parameters:

Name	Type	Description	Default
`content`	`bytes \| BinaryIO \| str \| Path \| None`	Archive content to unpack into the new directory, supplied as raw bytes or an open binary stream, or a path to an existing source directory to copy in. When `None`, an empty directory is created.	`None`
`archive_file_format`	`Literal['zip', 'tar', 'gztar', 'bztar', 'xztar'] \| None`	The archive format used to interpret `content` when unpacking. Must be set whenever `content` is archive content; ignored when `content` is a source directory path or `None`.	`None`
`name`	`str \| None`	A human-readable display name for the artifact. When `None`, the artifact's generated UUID is used as its name.	`None`
`description`	`str`	A short human-readable description of the artifact. Defaults to an empty string when omitted.	`''`
`resource_id`	`str \| UUID \| None`	A previously reserved resource ID to claim for this artifact. When `None`, a new ID is generated automatically.	`None`
`agent_id`	`str \| UUID \| None`	The ID of the agent that produced this artifact, recorded for attribution. When `None`, the artifact is stored with no producing agent.	`None`

Returns:

Type	Description
`Artifact`	The newly created artifact directory resource.

Raises:

Type	Description
`AgentNotFoundError`	If `agent_id` is provided but no agent with that ID is registered.
`ResourceIDReservationNotFoundError`	If `resource_id` is provided but has no corresponding reservation.
`InvalidRepositoryDirectoryArchiveFileFormatError`	If `content` is archive content that cannot be unpacked as `archive_file_format`, or if `archive_file_format` is not set.
`RepositoryResourceFileSystemError`	If the directory cannot be created or the source directory or archive cannot be unpacked into it.
`RepositoryMetadataFileSystemError`	If the artifact metadata cannot be written to disk after the directory is created.

`add_artifact_directory(path, name=None, description='', resource_id=None, copy=False, agent_id=None)` `async` ¶

Registers an existing directory on disk as an artifact.

Unlike create_artifact_directory, no new directory is created: the directory at path is moved (or copied when copy=True) into the artifacts repository, registered as a resource, and an ARTIFACT_CREATED event is emitted. When an agent_id is supplied the producing agent is resolved and recorded for attribution.

Parameters:

Name	Type	Description	Default
`path`	`Path \| str`	Filesystem path to the existing directory to ingest as an artifact.	required
`name`	`str \| None`	A human-readable display name for the artifact. When `None`, the original directory name is used.	`None`
`description`	`str`	A short human-readable description of the artifact. Defaults to an empty string when omitted.	`''`
`resource_id`	`str \| UUID \| None`	A previously reserved resource ID to claim for this artifact. When `None`, a new ID is generated automatically.	`None`
`copy`	`bool`	When `False` (default) the source directory is moved into the repository, leaving nothing at the original path. When `True` the source directory is copied and the original is left in place.	`False`
`agent_id`	`str \| UUID \| None`	The ID of the agent that produced this artifact, recorded for attribution. When `None`, the artifact is stored with no producing agent.	`None`

Returns:

Type	Description
`Artifact`	The newly registered artifact directory resource.

Raises:

Type	Description
`AgentNotFoundError`	If `agent_id` is provided but no agent with that ID is registered.
`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 artifact metadata cannot be written to disk afterwards.

`update_artifact_by_resource_id(resource_id, name=None, description=None, agent_id=_UNSET)` `async` ¶

Updates an artifact's mutable metadata.

name and description are updated in place when provided. The artifact's stored data is only rebuilt when agent_id is passed, mirroring the attribution parameter of the artifact creation methods: the given agent is resolved into a stored reference exactly as it would be on creation. When agent_id is omitted the existing data is left untouched. An ARTIFACT_UPDATED event is emitted.

Parameters:

Name	Type	Description	Default
`resource_id`	`str \| UUID`	The ID of the artifact to update.	required
`name`	`str \| None`	A new human-readable display name for the artifact. When `None`, the existing name is preserved.	`None`
`description`	`str \| None`	A new description for the artifact. When `None`, the existing description is preserved.	`None`
`agent_id`	`str \| UUID \| None`	When provided, rebuilds the artifact's attribution data from this agent ID (or clears attribution when `None`). When omitted entirely, the artifact's existing data is left unchanged.	`_UNSET`

Returns:

Type	Description
`Artifact`	The updated artifact resource.

Raises:

Type	Description
`ResourceNotFoundError`	If no artifact with the given ID exists.
`AgentNotFoundError`	If `agent_id` is provided but no agent with that ID is registered.
`RepositoryMetadataFileSystemError`	If the updated metadata cannot be written to disk.

`delete_artifact_by_resource_id(resource_id)` `async` ¶

Deletes an artifact from disk and the repository.

The artifact's metadata is snapshotted before removal so it can be carried on the emitted ARTIFACT_DELETED event, then the resource is deleted from disk and deregistered.

Parameters:

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

An artifact 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 artifact with the given ID exists.
`RepositoryResourceFileSystemError`	If the artifact's file or directory exists on disk but cannot be deleted.
`RepositoryMetadataFileSystemError`	If the metadata file cannot be written to disk after deletion.

`get_all_artifacts()` ¶

Returns every artifact currently tracked by the artifacts service.

Returns:

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

`get_artifact_by_resource_id(resource_id)` ¶

Returns a single artifact by its ID.

Parameters:

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

Returns:

Type	Description
`Artifact`	The requested artifact resource, either a file or a directory depending on how it was created.

Raises:

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

Artifacts service¶

consortium.server.services.artifacts_service ¶