soulfire.client.SoulFireInstance

class soulfire.client.SoulFireInstance(instance_id: str, bot_service: soulfire.bot_connect.BotServiceClient, bot_live: soulfire.bot_live_connect.BotLiveServiceClient, instance_service: soulfire.instance_connect.InstanceServiceClient, mc_auth_service: soulfire.mc_auth_connect.MCAuthServiceClient | None = None, bot_tasks: soulfire.task_connect.BotTaskServiceClient | None = None, pathfinder_service: soulfire.pathfinding_connect.PathfinderServiceClient | None = None, chat_service: soulfire.chat_connect.ChatServiceClient | None = None, inventory_service: soulfire.inventory_connect.InventoryServiceClient | None = None, recipe_service: soulfire.recipe_connect.RecipeServiceClient | None = None, registry_service: soulfire.registry_connect.RegistryServiceClient | None = None, world_service: soulfire.world_connect.WorldServiceClient | None = None, protocol_service: soulfire.protocol_connect.BotProtocolServiceClient | None = None, capabilities: soulfire.connection.CapabilitySet | None = None, instance_live: soulfire.instance_live_connect.InstanceLiveServiceClient | None = None)[source]

An instance handle that groups bot accounts and configuration.

Obtain a handle from SoulFire.instance() or SoulFire.get_or_create_instance(). Use get_or_create_bot() for normal provisioning and bot() for an existing bot UUID. The instance itself persists after the client scope closes.

id
property fleet: soulfire.fleet.SoulFireFleet
get_or_create_bot(name: str, *, auth: Literal['offline', 'microsoft'] = 'offline', username: str | None = None, start: bool = True, ready_timeout: float = 30.0, on_device_code: collections.abc.Callable[[soulfire.mc_auth_pb2.DeviceCode], effect_py.Effect[None, soulfire.errors.SoulFireOperationError]] | None = None, timeout_ms: int | None = None) → effect_py.Effect[soulfire.bot.SoulFireBot, soulfire.errors.SoulFireOperationError, effect_py.Scope][source]

Provision a named account and return a bot, ready by default.

Bot names belong to this instance. Repeated calls reuse the named account; conflicting usernames or authentication methods fail explicitly. With start=True, this operation calls SoulFireBot.connect(). Scope cleanup stops a bot started by the SDK and preserves a bot that was already running. The account remains in the instance.

Parameters:

  • name – Stable bot name within this instance.

  • auth – "offline" or "microsoft". Defaults to "offline".

  • username – Minecraft username for provisioning an offline account.

  • start – Start and observe the bot when true. With false, returns an unconnected handle for configuration before SoulFireBot.connect().

  • ready_timeout – Positive, finite readiness deadline in seconds. Defaults to 30 and applies when start is true.

  • on_device_code – Effect callback for Microsoft device-code login. Without a callback, the SDK prints the sign-in URL and code.

  • timeout_ms – RPC timeout in milliseconds.

Returns:

An Effect that produces a bot handle. Requires Scope.

bot(bot_id: str) → soulfire.bot.SoulFireBot[source]

Create a bot handle without a network request or readiness wait.

Parameters:

bot_id – Existing bot UUID, not its username or provisioning name.

Returns:

A bot handle with no attached observation session. Use SoulFireBot.connect() for scoped readiness and live state.

info(*, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[soulfire.instance_pb2.InstanceInfo, soulfire.errors.SoulFireOperationError][source]
delete(*, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[None, soulfire.errors.SoulFireOperationError][source]
update_name(friendly_name: str, *, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[None, soulfire.errors.SoulFireOperationError][source]
set_config_entry(namespace: str, key: str, value: Any, *, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[None, soulfire.errors.SoulFireOperationError][source]
add_accounts(accounts: collections.abc.Iterable[soulfire.common_pb2.MinecraftAccountProto], *, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[None, soulfire.errors.SoulFireOperationError][source]
remove_accounts(profile_ids: collections.abc.Iterable[str], *, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[None, soulfire.errors.SoulFireOperationError][source]
add_proxies(proxies: collections.abc.Iterable[soulfire.common_pb2.ProxyProto], *, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[None, soulfire.errors.SoulFireOperationError][source]
remove_proxies(addresses: collections.abc.Iterable[str], *, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[None, soulfire.errors.SoulFireOperationError][source]
login_credentials(service: soulfire.common_pb2.AccountTypeCredentials, payload: collections.abc.Iterable[str], *, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → soulfire.streams.Stream[soulfire.mc_auth_pb2.CredentialsAuthResponse, soulfire.errors.SoulFireOperationError][source]
login_device_code(service: soulfire.common_pb2.AccountTypeDeviceCode, *, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → soulfire.streams.Stream[soulfire.mc_auth_pb2.DeviceCodeAuthResponse, soulfire.errors.SoulFireOperationError][source]
refresh_account(account: soulfire.common_pb2.MinecraftAccountProto, *, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[soulfire.mc_auth_pb2.RefreshResponse, soulfire.errors.SoulFireOperationError][source]
bots(*, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[list[soulfire.bot_pb2.BotListEntry], soulfire.errors.SoulFireOperationError][source]
watch_bot_statuses(*, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → soulfire.streams.Stream[soulfire.bot_pb2.WatchBotStatusesResponse, soulfire.errors.SoulFireOperationError][source]
events(filter: soulfire.instance_live_pb2.InstanceEventFilter | None = None, *, bot_ids: collections.abc.Iterable[str] = (), headers: dict[str, str] | None = None, timeout_ms: int | None = None) → soulfire.streams.Stream[soulfire.instance_live_pb2.InstanceEvent, soulfire.errors.SoulFireOperationError][source]

Watch one multiplexed event stream for bots in this instance.

start(*, bot_ids: collections.abc.Iterable[str] | None = None, count: int | None = None, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[list[soulfire.bot_pb2.BotStatus], soulfire.errors.SoulFireOperationError][source]
stop(*, bot_ids: collections.abc.Iterable[str] | None = None, count: int | None = None, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[list[soulfire.bot_pb2.BotStatus], soulfire.errors.SoulFireOperationError][source]
restart(*, bot_ids: collections.abc.Iterable[str] | None = None, count: int | None = None, headers: dict[str, str] | None = None, timeout_ms: int | None = None) → effect_py.Effect[list[soulfire.bot_pb2.BotStatus], soulfire.errors.SoulFireOperationError][source]