arc-agents/lib/types/registry.d.ts

A library for creating and deploying gaming agents at scale

import { ModelType } from "./utils";

/** Represents a the bounds for a feature in the state space. */
type StateBounds = {
  type: "range" | "set", // The type of bounds
  range?: { min: number, max: number }, // Min and max for the range bounds (continuous bounds)
  set?: number[] // Values allowed in the set bounds (discrete bounds)
}

/** Represents a slot in the registry. */
export interface Slot {
  gameId: string; // Unique identifier for the game
  architectureId: string; // Unique identifier for the architecture
  modelType: ModelType; // Type of the model
  inputDim: number; // Input dimensionality of the model
  actionNames: string[]; // Names of the action heads
  actionOrder: string[][]; // Action names for each of the heads
  stateBounds?: StateBounds[]; // Bounds for the state space of the model
}

/** Represents the inputs required to register a new model architecture. */
type RegistrationInputs = {
  modelType: ModelType, // The type of the model.
  architectureId: string, // The unique ID for the architecture.
  inputDim: number, // The input dimensionality of the model.
  actions: { [key: string]: string[] }, // The available actions for each of the model's heads.
  stateBounds?: StateBounds[], // The bounds for the model's state space.
}

/**
 * The Registry class provides methods to interact with the backend for managing registry slots.
 */
export declare class Registry {
  /**
   * Static API key used for authentication in requests.
   * This must be set before making any API calls.
   */
  static apiKey: string;

  /**
   * Static backend url used to send network requests to the ARC server
   * Can be optionally overridden
   */
  static backend: string;

  /** The game ID associated with this registry. */
  gameId: string;

  /**
   * List of registered slots. This property is fetched dynamically and may not be initialized.
   */
  registrySlots?: Slot[];

  /**
   * Maximum number of slots available in the registry. This value is set after fetching slots.
   */
  maxSlots?: number;

  /**
   * Creates a new Registry instance for a specific game.
   * @param gameId - The ID of the game associated with this registry.
   */
  constructor(gameId: string);

  /** Gets the api key for the agent vars class */
  static getApiKey(): string;

  /**
   * Sets the api key for the agent vars class
   * @param apiKey - The api key for the user.
   */  
  static setApiKey(apiKey: string): void;      

  /**
   * Overrides the default backend url.
   * @param newBackend - The new url for the backend.
   */
  static overrideBackendUrl(newBackend: string): void;

  /**
   * Fetches the registered slots for the game from the backend.
   * Updates `registrySlots` and sets the maximum number of slots (`maxSlots`).
   * @returns A promise that resolves when the slots have been fetched.
   */
  fetchRegistrySlots(): Promise<void>;

  /**
   * Unregisters a model from the registry.
   * @param architectureId - The ID of the architecture to unregister.
   * @returns A promise that resolves when the model has been unregistered.
   */
  unregister(architectureId: string): Promise<void>;

  /**
   * Registers a new model architecture in the registry.
   * @param RegistrationInputs - The inputs for the new model architecture.
   * @returns A promise that resolves when the model architecture has been registered.
   */
  register(registrationInputs: RegistrationInputs): Promise<void>;

  /**
   * Prints the current registry slots to the console.
   * If `registrySlots` is undefined, it first fetches the slots from the backend.
   * Displays both registered and empty slots.
   * @returns A promise that resolves when the slots have been printed.
   */
  printSlots(): Promise<void>;
}