Agent file manager service¶

`consortium.server.services.agent_file_manager_service` ¶

`AgentFileManagerService(agent)` ¶

`get_all_assets()` ¶

Returns all asset resources available to the agent.

Returns:

Type	Description
`list[Asset]`	A list of all asset resources. Empty if none have been uploaded.

`get_asset_by_asset_id(asset_id)` ¶

Returns a single asset resource by its ID.

Parameters:

Name	Type	Description	Default
`asset_id`	`str \| UUID`	The ID of the asset resource to retrieve.	required

Returns:

Type	Description
`Asset`	The requested asset resource.

Raises:

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

`get_all_artifacts()` ¶

Returns all artifact resources produced by agents.

Returns:

Type	Description
`list[Artifact]`	A list of all artifact resources. Empty if none have been created.

`get_artifact_by_artifact_id(artifact_id)` ¶

Returns a single artifact resource by its ID.

Parameters:

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

Returns:

Type	Description
`Artifact`	The requested artifact resource.

Raises:

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

`read_asset_by_asset_id(asset_id, binary=False, encoding='utf-8', chunk_size=None)` ¶

Reads the content of a file asset by its ID.

Retrieves the asset and reads its content from disk. The full read spectrum of the underlying repository file is exposed: content can be read as text or as raw bytes, and either eagerly (the whole content at once) or lazily as a generator of chunks for streaming large assets without loading them fully into memory.

Parameters:

Name	Type	Description	Default
`asset_id`	`str \| UUID`	The ID of the asset to read.	required
`binary`	`bool`	When `True`, the content is read as raw bytes; when `False` (default) it is decoded to text using `encoding`.	`False`
`encoding`	`str`	The text encoding used to decode the content when `binary` is `False`. Ignored when `binary` is `True`.	`'utf-8'`
`chunk_size`	`int \| None`	When `None` (default) the entire content is read and returned in one piece. When set to a positive integer, a generator is returned that yields the content in chunks of at most this many bytes (binary) or characters (text), for streaming.	`None`

Returns:

Type	Description
`str \| bytes \| Generator[str \| bytes]`	The asset's content: a `str` (text) or `bytes` (binary) when `chunk_size` is `None`, otherwise a generator yielding successive `str` or `bytes` chunks.

Raises:

Type	Description
`ResourceNotFoundError`	If no asset with the given ID exists.
`IsADirectoryError`	If the asset is a directory, which has no readable file content.
`RepositoryFileDoesNotExistError`	If the asset is a file but no longer exists on disk. Always raised immediately, before any content is read, even when `chunk_size` is set: existence is checked before the generator is built.
`RepositoryResourceFileSystemError`	If reading the file from disk fails for a reason other than it being missing (for example a permissions error). Raised immediately when `chunk_size` is `None`. When `chunk_size` is set, the file is not opened until the returned generator is first iterated, so this is raised on that first iteration instead, not when this method is called.
`LookupError`	If `encoding` names an encoding Python does not recognize. Never raised when `binary` is `True`, since `encoding` is then ignored. Same call-time-versus-first-iteration timing as `RepositoryResourceFileSystemError` above.
`UnicodeDecodeError`	If the file's content cannot be decoded using `encoding`. Never raised when `binary` is `True`. Same timing as `LookupError` above.

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

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

The content is written to a new file in the artifacts repository and attributed to the owning agent.

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 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.	`''`

Returns:

Type	Description
`Artifact`	The newly created artifact file resource, attributed to the owning agent.

Raises:

Type	Description
`AgentNotFoundError`	If the owning agent is no longer registered.
`RepositoryResourceFileSystemError`	If the artifact file cannot be written to disk.
`RepositoryMetadataFileSystemError`	If the repository's metadata file cannot be written to disk after the artifact file is created.
`UnicodeDecodeError`	If `content` is a text stream whose underlying data cannot be decoded while it is being read to write the artifact file. Left unwrapped: it describes the content supplied rather than a failure of the artifacts repository itself.

`add_artifact_file(path, name=None, description='', copy=False)` `async` ¶

Registers an existing file on disk as an artifact.

No new content is written: the file at path is moved (or copied when copy=True) into the artifacts repository and attributed to the owning agent.

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.	`''`
`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`

Returns:

Type	Description
`Artifact`	The newly registered artifact file resource, attributed to the owning agent.

Raises:

Type	Description
`AgentNotFoundError`	If the owning agent is no longer registered.
`RepositoryResourceFileSystemError`	If no file exists at `path`, or the file cannot be moved or copied into the artifacts repository.
`RepositoryMetadataFileSystemError`	If the repository's metadata file cannot be written to disk afterwards.

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

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

An empty directory is created 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. The directory is attributed to the owning agent.

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.	`''`

Returns:

Type	Description
`Artifact`	The newly created artifact directory resource, attributed to the owning agent.

Raises:

Type	Description
`AgentNotFoundError`	If the owning agent is no longer registered.
`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 artifact directory cannot be created, or the source directory or archive cannot be copied or unpacked into it.
`RepositoryMetadataFileSystemError`	If the repository's metadata file cannot be written to disk after the artifact directory is created.

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

Registers an existing directory on disk as an artifact.

No new directory is created: the directory at path is moved (or copied when copy=True) into the artifacts repository and attributed to the owning agent.

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.	`''`
`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`

Returns:

Type	Description
`Artifact`	The newly registered artifact directory resource, attributed to the owning agent.

Raises:

Type	Description
`AgentNotFoundError`	If the owning agent is no longer registered.
`RepositoryResourceFileSystemError`	If no directory exists at `path`, or the directory or any file within it cannot be moved or copied into the artifacts repository.
`RepositoryMetadataFileSystemError`	If the repository's metadata file cannot be written to disk afterwards.

Agent file manager service¶

consortium.server.services.agent_file_manager_service ¶