AgentManager

AgentManager is a utility to assist in spawning agents and keeping genome files in a centralized location.

This class also persists agent configuration information between instantiations, so that previously used genomes can be referenced from the genome store. Will automatically provide an AgentClient object when agent is spawned using manager.

Note

Requires access to the Docker Daemon running on the user’s computer, and access to Intelligent Artifact’s GAIuS Docker images.

Quickstart

from ia.gaius.manager import AgentManager

am = AgentManager()
am.kill_all_agents()
agent = am.start_agent(genome_file='simple.genome', agent_id='pvt', connect_jia=True, api_key='SECRET1234')
agent_client = agent.get_agent_client()

AgentManager

class ia.gaius.manager.AgentManager(genome_dir: Path | None = None, agents_dir: Path | None = None, thinkflux_dir: Path | None = None, comcom_dir: Path | None = None, local: bool = False)

Bases: object

__init__(genome_dir: Path | None = None, agents_dir: Path | None = None, thinkflux_dir: Path | None = None, comcom_dir: Path | None = None, local: bool = False)

Initialize AgentManager object (setup dirs, etc.)

This object can be used to spawn Agents using the start_agent() method.

add_genome(genome_file: dict)

add genome from provided filepath

Parameters:: genome_file (str) – genome file to add to AgentManager
Raises:: Exception – When genome not found
Returns:: contents of genome file
Return type:: dict

agent_context(genome_file: str = None, genome_name: str = None, user_id: str = 'jia', agent_id: str = '1', agent_name: str = None, connect_jia=True, api_key='ABCD-1234')

Provide ability to use Agent as a context manager. Internally calls start_agent and stop_agent.

Parameters:

genome_file (_type_, optional) – _description_. Defaults to None.
genome_name (_type_, optional) – _description_. Defaults to None.
user_id (str, optional) – _description_. Defaults to ‘jia’.
agent_id (str, optional) – _description_. Defaults to ‘1’.
agent_name (_type_, optional) – _description_. Defaults to None.
connect_jia (bool, optional) – _description_. Defaults to True.
api_key (str, optional) – _description_. Defaults to ‘ABCD-1234’.

Yields:

_type_ – _description_

delete_agent(agent_name)

Stop/Delete agent & remove config file from agents_dir

Parameters:: agent_name (str) – name of agent to stop
Returns:: string depicting deletion status
Return type:: str

delete_comcom(name: str)

delete_genome(genome_name)

Delete genome from centralized genome_dir

Parameters:: genome_name (str) – genome name to delete

delete_tf(tf_name: str)

Kill a Thinkflux container using it’s tf_name attribute

Parameters:: tf_name (str) – attribute passed when spawning Thinkflux
Raises:: Exception – When config not found

get_all_agent_status()

Get the status of all agents in current_agents dict

Returns:: { agent_name : alive? }
Return type:: dict

get_genome(genome_name)

Get genome by name, return as dict

Parameters:: genome_name (str) – filename for genome in genome_dir
Raises:: Exception – When genome not found
Returns:: contents of genome file
Return type:: dict

kill_all_agents(update=True)

Kill all agents known to AgentManager

Parameters:: update (bool, optional) – Whether to update AgentManager information before killing containers. Defaults to True.

list_genomes()

List the genomes present in the localized genome store

Returns:: list of genome files
Return type:: list

remediate_dead_agents(): Remove all agents that cannot be pinged.

start_agent(genome_file=None, genome_name=None, user_id: str = 'jia', agent_id: str = '1', agent_name=None, connect_jia=True, api_key='ABCD-1234', single_container=False, **kwargs) → AgentInfo

Spawn an agent and save its information in the localized agents dir

Note

If you wish to use a genome that has not been used by the AgentManager before, pass it in the genome_file field. This will retrieve the genome from the specified path, and save it in the localized genome dir for future use.

Parameters:

genome_file (str, optional) – Path to outside genome file. Defaults to None.
genome_name (str, optional) – Name of genome in the localized genome dir. Defaults to None.
user_id (str, optional) – user id for naming docker containers. Defaults to ‘jia’.
agent_id (str, optional) – agent id for naming docker containers. Defaults to ‘1’.
agent_name (_type_, optional) – descriptive name “alias” for agent. Defaults to None.
connect_jia (bool, optional) – Whether to attempt to connect agent to Jia docker container. Defaults to True.
api_key (str, optional) – Control the api key used to access agent. Defaults to ‘ABCD-1234’.

Raises:

Exception – If there is a conflicting agent with user_id and agent_id already present/alive

Returns:

AgentInfo object corresponding to started agent. can be used to retrieve AgentClient object using AgentInfo.get_agent_client()

Return type:

AgentInfo

start_comcom(name: str, api_key: str, docker_image: str, port: int = 8081, comcom_id: str = '1', agents_to_connect: list | None = None, additional_ports: Dict[str, int] = {}, volumes: dict | None = None) → ComcomInfo

start_hoster(): Start dvdarias/docker-hoster docker container to resolve container hostnames into IP addresses. More friendly for AgentManager usage

start_tf(tf_name: str, api_key: str, docker_image: str, port: int = 8090, user_id: str = 'tf', tf_id: str = '1', environment: dict | None = None, privileged: bool | None = None, volumes: dict | None = None, agents_to_connect: list | None = None) → TFInfo

Spawn a Thinkflux container using provided config. Store config in AgentManager

Container name is defined as:: “tf-{user_id}-{tf_id}”

Parameters:

tf_name (str) – descriptive name “alias” for Thinkflux
api_key (str) – Passed as API_KEY env variable to container
docker_image (str) – Container image to spawn. E.g. “registry.digitalocean.com/intelligent-artifacts/thinkflux:develop”
port (int, optional) – _description_. Defaults to 8090.
user_id (str, optional) – user_id portion of container extension. Defaults to ‘tf’.
tf_id (str, optional) – tf_id portion of container extension. Defaults to ‘1’.
environment (dict, optional) – additional environment variables to provide to container, as key-value pairs. Defaults to None.
privileged (bool, optional) – run container in privileged mode. Defaults to None.
volumes (dict, optional) – volumes to mount in container as key-value pairs. Defaults to None.
agents_to_connect (list, optional) – list of agents to connect to Thinkflux. Defaults to None.

Raises:

Exception – If invalid agents passed in agents_to_connect
Exception – If tf_name already exists in AgentManager
Exception – If a thinkflux with user_id and tf_id already exists in AgentManager

Returns:

Object corresponding to spawned Thinkflux

Return type:

TFInfo

stop_hoster(): Stop dvdarias/docker-hoster docker container

update_current_agents(): Update AgentManager’s list of configured agents, thinkflux, comcom, genomes

AgentInfo

class ia.gaius.manager.AgentInfo(user_id: str, agent_id: str, agent_name: str, genome_name: str | None = None, genome_file: str | None = None, agent_config=None, location: str = 'local', LOG_LEVEL=20, api_key='ABCD-1234', genome_dir=None, agents_dir=None, genome=None, single_container: bool = False, local_agent_config=None, version='latest', **kwargs)

Bases: object

__init__(user_id: str, agent_id: str, agent_name: str, genome_name: str | None = None, genome_file: str | None = None, agent_config=None, location: str = 'local', LOG_LEVEL=20, api_key='ABCD-1234', genome_dir=None, agents_dir=None, genome=None, single_container: bool = False, local_agent_config=None, version='latest', **kwargs)

Wrapper class for Agent information. Used to start/stop agents, and save config information to a central location

Parameters:

user_id (str) – User id attached to docker contaienrs spawned using AgentInfo
agent_id (str) – Agent id attached to docker containers spawned using AgentInfo
agent_name (str) – Descriptive, user-friendly name to refer to agent by
genome_name (str, optional) – If genome already in centralized location, refer to it by its name
genome_file (str, optional) – To copy outside genome into genome store, provide filepath here
agent_config (_type_, optional) – Stores AgentConfig details once agent is spawned.
location (str, optional) – In future will support spawning at several locations (local, private cloud, DigitalOcean, etc). Defaults to ‘local’.
LOG_LEVEL (logging.LEVEL, optional) – Used to control verbosity of messages in agent spawn script. Defaults to logging.INFO.
api_key (str, optional) – Used to set API KEY of spawned agent. Defaults to “ABCD-1234”

check_running()

Check if we can access the agent

Returns:: True for success, False for failure
Return type:: bool

connect_jia(): Connect agent to jia (add jia to the agent’s network)

delete_config_file(): Kill agent and delete config information from agents directory

classmethod fromFile(filepath: str | Path)

Construct AgentInfo object from file

Parameters:: filepath (str) – path to file to load
Returns:: AgentInfo object created from the file
Return type:: AgentInfo

classmethod fromJSON(json_obj)

Construct AgentInfo from JSON object

Parameters:: json_obj (dict) – Contains fields necessary for constructing AgentInfo
Returns:: AgentInfo object created from JSON object
Return type:: AgentInfo

get_agent_client(local: bool = False)

Retreive AgentClient object from started agent

Returns:: ia.gaius.agent_client.AgentClient

get_docker_networks()

Get names of networks this agent is a part of (uses gaius-api-{user_id}-{agent_id})

Raises:: Exception – More that one container found with same name
Returns:: list of networks
Return type:: _type_

kill_agent(): Attempt to kill a running agent

save_config_file(): Store config information for agent in agents directory, based on agent name

spawn(connect_jia=True)

Start a new agent using information provided in constructor

Parameters:: api_key (str, optional) – API Key for agent. Defaults to “ABCD-1234”.

toJSON()

Dump config information to a JSON object (dict)

Returns:: config information
Return type:: dict

TFInfo

class ia.gaius.manager.TFInfo(user_id: str, tf_id: str, tf_name: str, location: str, api_key: str, thinkflux_dir: str, docker_image: str, port: int, privileged: bool = False, environment: dict | None = None, volumes: dict | None = None, **kwargs)

Bases: object

__init__(user_id: str, tf_id: str, tf_name: str, location: str, api_key: str, thinkflux_dir: str, docker_image: str, port: int, privileged: bool = False, environment: dict | None = None, volumes: dict | None = None, **kwargs) → None

connect_agents(agents: List[AgentInfo])

delete_config_file(): delete config information from agents directory

classmethod fromFile(filepath: str | Path)

Construct AgentInfo object from file

Parameters:: filepath (str) – path to file to load
Returns:: AgentInfo object created from the file
Return type:: AgentInfo

classmethod fromJSON(json_obj)

Construct AgentInfo from JSON object

Parameters:: json_obj (dict) – Contains fields necessary for constructing AgentInfo
Returns:: AgentInfo object created from JSON object
Return type:: AgentInfo

kill()

save_config_file(): Store config information for agent in agents directory, based on agent name

spawn() → bool

toJSON()

Dump config information to a JSON Object

Returns:: config information
Return type:: dict