diff --git a/404.html b/404.html index 7be67e0..466a3c2 100644 --- a/404.html +++ b/404.html @@ -9,13 +9,13 @@ - +
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- + \ No newline at end of file diff --git a/assets/js/50751b0a.2a9afa79.js b/assets/js/50751b0a.2a9afa79.js deleted file mode 100644 index 2f64c57..0000000 --- a/assets/js/50751b0a.2a9afa79.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkcogment_doc=self.webpackChunkcogment_doc||[]).push([[8687],{3905:(e,t,r)=>{r.d(t,{Zo:()=>d,kt:()=>m});var n=r(7294);function i(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function a(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,n)}return r}function o(e){for(var t=1;t=0||(i[r]=e[r]);return i}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(i[r]=e[r])}return i}var s=n.createContext({}),c=function(e){var t=n.useContext(s),r=t;return e&&(r="function"==typeof e?e(t):o(o({},t),e)),r},d=function(e){var t=c(e.components);return n.createElement(s.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},h=n.forwardRef((function(e,t){var r=e.components,i=e.mdxType,a=e.originalType,s=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),h=c(r),m=i,u=h["".concat(s,".").concat(m)]||h[m]||p[m]||a;return r?n.createElement(u,o(o({ref:t},d),{},{components:r})):n.createElement(u,o({ref:t},d))}));function m(e,t){var r=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var a=r.length,o=new Array(a);o[0]=h;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,o[1]=l;for(var c=2;c{r.r(t),r.d(t,{assets:()=>s,contentTitle:()=>o,default:()=>p,frontMatter:()=>a,metadata:()=>l,toc:()=>c});var n=r(7462),i=(r(7294),r(3905));const a={title:"Server",sidebar_position:1},o="Directory Server",l={unversionedId:"reference/cli/directory/directory-server",id:"reference/cli/directory/directory-server",title:"Server",description:"The Directory is an implementation of the directory gRPC service. It is the service to find other services. Typically, every other Cogment service only needs to know the address of the Directory to access anything in Cogment.",source:"@site/docs/reference/cli/directory/directory-server.md",sourceDirName:"reference/cli/directory",slug:"/reference/cli/directory/directory-server",permalink:"/docs/reference/cli/directory/directory-server",draft:!1,tags:[],version:"current",lastUpdatedAt:1697135297,formattedLastUpdatedAt:"Oct 12, 2023",sidebarPosition:1,frontMatter:{title:"Server",sidebar_position:1},sidebar:"docSidebar",previous:{title:"Orchestrator",permalink:"/docs/reference/cli/orchestrator"},next:{title:"Client",permalink:"/docs/reference/cli/directory/directory-client"}},s={},c=[{value:"Command line",id:"command-line",level:2},{value:"Options",id:"options",level:2},{value:"port",id:"port",level:3},{value:"grpc_reflection",id:"grpc_reflection",level:3},{value:"log_level",id:"log_level",level:3},{value:"log_file",id:"log_file",level:3},{value:"registration_lag",id:"registration_lag",level:3},{value:"persistence_file",id:"persistence_file",level:3},{value:"load_balancing",id:"load_balancing",level:3},{value:"check_on_inquire",id:"check_on_inquire",level:3},{value:"Operation",id:"operation",level:2},{value:"Health Checking",id:"health-checking",level:3},{value:"Load Balancing",id:"load-balancing",level:3},{value:"Data",id:"data",level:3}],d={toc:c};function p(e){let{components:t,...r}=e;return(0,i.kt)("wrapper",(0,n.Z)({},d,r,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("h1",{id:"directory-server"},"Directory Server"),(0,i.kt)("p",null,"The Directory is an implementation of the ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/grpc#directory-api"},"directory gRPC service"),". It is the service to find other services. Typically, every other Cogment service only needs to know the address of the Directory to access anything in Cogment."),(0,i.kt)("p",null,"A regular health check is done on non-permanent network services to make sure they remain available (i.e. network reachable).\nIf a service fails the health check, it is automatically removed from the Directory."),(0,i.kt)("p",null,"The Directory works in tandem with the Cogment ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/parameters#cogment-endpoints"},"endpoints"),", in particular the ones with a ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/parameters#discover-host"},"discover host")," (referred as ",(0,i.kt)("strong",{parentName:"p"},"discovery endpoints"),")."),(0,i.kt)("p",null,"A ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/cli/directory/directory-client"},"Directory Client")," is also part of the Cogment CLI to access the Directory from the command line."),(0,i.kt)("h2",{id:"command-line"},"Command line"),(0,i.kt)("p",null,"The Directory is a Cogment CLI service:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"$ cogment services directory --port=9005\n")),(0,i.kt)("h2",{id:"options"},"Options"),(0,i.kt)("h3",{id:"port"},(0,i.kt)("inlineCode",{parentName:"h3"},"port")),(0,i.kt)("p",null,"The TCP port where to serve the ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/grpc#directory-api"},"directory gRPC service"),". This is where the users of the Directory connect to."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--port"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_PORT"),","),(0,i.kt)("li",{parentName:"ul"},"default value is 9005.")),(0,i.kt)("h3",{id:"grpc_reflection"},(0,i.kt)("inlineCode",{parentName:"h3"},"grpc_reflection")),(0,i.kt)("p",null,"Whether or not to enable ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/grpc/grpc/blob/master/doc/server-reflection.md"},"gRPC reflection")," on the served directory endpoint."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--grpc_reflection"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_GRPC_REFLECTION=1"),","),(0,i.kt)("li",{parentName:"ul"},"by default, it is disabled.")),(0,i.kt)("h3",{id:"log_level"},(0,i.kt)("inlineCode",{parentName:"h3"},"log_level")),(0,i.kt)("p",null,"Set to define the minimum level for logging. Possible values are: ",(0,i.kt)("inlineCode",{parentName:"p"},"off"),", ",(0,i.kt)("inlineCode",{parentName:"p"},"error"),", ",(0,i.kt)("inlineCode",{parentName:"p"},"warning"),", ",(0,i.kt)("inlineCode",{parentName:"p"},"info"),", ",(0,i.kt)("inlineCode",{parentName:"p"},"debug"),", ",(0,i.kt)("inlineCode",{parentName:"p"},"trace"),"."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--log_level=debug"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_LOG_LEVEL=info"),","),(0,i.kt)("li",{parentName:"ul"},"default value is info.")),(0,i.kt)("h3",{id:"log_file"},(0,i.kt)("inlineCode",{parentName:"h3"},"log_file")),(0,i.kt)("p",null,"Base file name for daily log output. The name will be suffixed with the date and a new file will be made every day. If not provided, the logs go to stdout."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--log_file=./path/to/cogment.log"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_LOG_FILE=./path/to/cogment.log"),","),(0,i.kt)("li",{parentName:"ul"},"default value is info.")),(0,i.kt)("h3",{id:"registration_lag"},(0,i.kt)("inlineCode",{parentName:"h3"},"registration_lag")),(0,i.kt)("p",null,"The maximum number of seconds to wait before responding with no result (either due to a service not registered, or that has failed a health check).\nThis can be used when components may start at slightly different time, and some components may inquire about a component that did not have time to register yet.\nIt may also help when services sometimes go temporarily offline."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--registration_lag"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_REGISTRATION_LAG"),","),(0,i.kt)("li",{parentName:"ul"},"default value is 0.")),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},(0,i.kt)("a",{parentName:"p",href:"#load-balancing"},"Unserviceable"),' services are not considered for this lag.\nI.e. the directory will not wait for a service to become "serviceable".')),(0,i.kt)("h3",{id:"persistence_file"},(0,i.kt)("inlineCode",{parentName:"h3"},"persistence_file")),(0,i.kt)("p",null,"The file name where persistence data will be read from on start-up and stored afterward.\nThe file will be created if it does not already exist.\nIf set to an empty string, persistence will be disabled."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--persistence_file"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_PERSISTENCE_FILE"),","),(0,i.kt)("li",{parentName:"ul"},'default value is ".cogment-directory-data".')),(0,i.kt)("h3",{id:"load_balancing"},(0,i.kt)("inlineCode",{parentName:"h3"},"load_balancing")),(0,i.kt)("p",null,"Whether or not to enable ",(0,i.kt)("a",{parentName:"p",href:"#load-balancing"},"load balancing")," when services are inquired."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--load_balancing"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_LOAD_BALANCING=1"),","),(0,i.kt)("li",{parentName:"ul"},"by default, it is disabled.")),(0,i.kt)("h3",{id:"check_on_inquire"},(0,i.kt)("inlineCode",{parentName:"h3"},"check_on_inquire")),(0,i.kt)("p",null,"Whether or not to enable ",(0,i.kt)("a",{parentName:"p",href:"#health-checking"},"health checking")," when a service is matched by an inquiry (in addition to being checked periodically).\nThis can prevent unavailable services from being returned (before the periodic health check has time to run).\nIt can also allow load balancing to use more recent/dynamic values.\nBut it can significantly slow down directory inquiries, especially when a health check fails."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--check_on_inquire"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_CHECK_ON_INQUIRE=1"),","),(0,i.kt)("li",{parentName:"ul"},"by default, it is disabled.")),(0,i.kt)("h2",{id:"operation"},"Operation"),(0,i.kt)("p",null,"At its most basic, the Directory contains services searchable by type and property, and returns endpoints where to reach the matched services."),(0,i.kt)("p",null,'Every registered service has a unique ID (it is unique among currently registered services). When registering a service, the ID of the new service is provided with a "secret" key (a string).\nThis "secret" (in combination with the ID) is required to deregister the service.\nIf a new service matches an existing one (i.e. an inquiry would match them), it is considered a duplicate.\nDuplicates are acceptable for non-permanent services.\nFor permanent services (both the old and new services must be permanent), duplicates are not allowed; instead, an update of the old service is performed (i.e. the ID and secret are kept the same).'),(0,i.kt)("p",null,"Every service is also associated with an authentication token.\nThis token is provided by users when registering a new service, and it must be provided to inquire or deregister that service.\nFor example, any inquiry can only find services that have the same authentication token as the one provided to the inquiry.\nSimilarly for deregistering: a service cannot be deregistered without the appropriate authentication token.\nIn closed environments, the authentication token can be left empty to facilitate directory management."),(0,i.kt)("h3",{id:"health-checking"},"Health Checking"),(0,i.kt)("p",null,"Each entry is normally checked for connectivity on a regular basis (every 60 seconds), but can also be checked when an entry matches an inquiry (see ",(0,i.kt)("a",{parentName:"p",href:"#check_on_inquire"},"check_on_inquire"),")."),(0,i.kt)("p",null,"The type of the entry determines the extent of the health check.\nFor Cogment services, the ",(0,i.kt)("inlineCode",{parentName:"p"},"Status")," procedure will be called and a response expected.\nFor non-Cogment services, a simple tcp connection will be attempted, and if successful, the service will be considered healthy."),(0,i.kt)("p",null,"If a service fails the health check multiple times, it will be removed from the directory.\nBut after the first failure, the service will not be reported on inquiries until and unless it succeeds a health check."),(0,i.kt)("p",null,"When services are recovered from a persistence file, they will immediately be subjected to a health check."),(0,i.kt)("h3",{id:"load-balancing"},"Load Balancing"),(0,i.kt)("p",null,"By default load balancing is disabled, and thus when inquiring, the services returned are in increasing order of age (since registration).\nSo the first is always the most recently registered service."),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"Permanent services do not change their registration timestamp when updated.")),(0,i.kt)("p",null,"When load balancing is enabled, and an inquiry is made, the order of services returned is different:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},'For each service that match the inquiry, the last read "overall_load" ',(0,i.kt)("inlineCode",{parentName:"li"},"Status")," (see below) is used. If ",(0,i.kt)("a",{parentName:"li",href:"#check_on_inquire"},"check_on_inquire"),' is enabled, then the service\'s current "overall_load" is read at this point.'),(0,i.kt)("li",{parentName:"ol"},"Services with a load of 255 are considered unserviceable and removed from the list of potential candidates."),(0,i.kt)("li",{parentName:"ol"},"The service with the lowest load is found. That service, and services with a load close to that one, are retained."),(0,i.kt)("li",{parentName:"ol"},"The retained services are shuffled randomly, and returned as a reply to the inquiry.")),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"Non-Cogment services (with no ",(0,i.kt)("inlineCode",{parentName:"p"},"Status")," gRPC procedure) are always considered fully available (with a load of 0).\nAnd thus will always be returned, but in random order, when load balancing is enabled.")),(0,i.kt)("p",null,"The ",(0,i.kt)("inlineCode",{parentName:"p"},"Status"),' gRPC procedure\'s "overall_load" status is expected to be a string representation of an integer from 0 to 255 (8 bit unsigned integer).\nIf the string cannot be converted to such an integer, a load of 0 is assumed (e.g. "256" will result in a load of 0).\nA normal value is between 0 and 100, representing the load on the machine where the service is running.\nA value of 0 means that there is no load, and a value of 100 means that the machine is very loaded (and may not be able to do processing in a timely manner).\nThe exact meaning of the value is dependent on the service reporting.\nA value of 255 indicates that the machine is not fit to run any new service (and thus it is "unserviceable").'),(0,i.kt)("h3",{id:"data"},"Data"),(0,i.kt)("p",null,"The Directory maintains the following data for each service:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"service ID"),": This is a numerical (64 bits unsigned integer) value generated by the Directory and assigned to the service on registration. It is unique to that service as long as it is in the Directory. Although very unlikely, it is possible for this ID to be re-used after the service is deregistered. Zero (0) is not a valid ID."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"endpoint"),": It consists of four distinct information:",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"protocol: The protocol (URL scheme) for the endpoint (",(0,i.kt)("inlineCode",{parentName:"li"},"grpc")," or ",(0,i.kt)("inlineCode",{parentName:"li"},"cogment"),"). The ",(0,i.kt)("inlineCode",{parentName:"li"},"cogment"),' protocol is not considered a "network" protocol and thus will not be checked for health (network connectivity).'),(0,i.kt)("li",{parentName:"ul"},"host: The host for the endpoint (e.g. somewhere.com). For the ",(0,i.kt)("inlineCode",{parentName:"li"},"grpc")," protocol this represents a TCP/IP network resource; it can be a network hostname or an IP address. For the ",(0,i.kt)("inlineCode",{parentName:"li"},"cogment")," protocol it must be a registered name (see ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/parameters#cogment-endpoints"},"cogment endpoints"),") and typically does not represent a network resource."),(0,i.kt)("li",{parentName:"ul"},"port: The TCP port where the registered service is providing its services. This is required for ",(0,i.kt)("inlineCode",{parentName:"li"},"grpc")," protocol hosts."),(0,i.kt)("li",{parentName:"ul"},"ssl requirement: Whether the service requires an encrypted SSL connection."))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"type"),": The type of service. This also determines how health checks are performed on the service (i.e. which gRPC service should be used to check the health of the service).",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"client actor connection: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-clientactorsp"},"client actor")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"trial lifecycle management: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-triallifecyclesp"},"lifecycle")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"actor: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-actor-api"},"actor")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"environment: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-environmentsp"},"environment")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"pre-hook: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-trialhookssp"},"pre-hook")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"datalog: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-logexportersp"},"datalog")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"datastore: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-trialdatastoresp"},"datastore")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"model registry: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-modelregistrysp"},"model registry")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"other: This type of service does not provide a gRPC API service or it is not a type of service known to Cogment. Only the ability to perform a tcp connection will be tested for health checking."))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"permanent"),": This determines if the service should be kept in the directory regardless of health (network connectivity). It also prevents duplication of the service in the directory (i.e. if a duplicate is registered, the service will just be updated with the new information, and keep the same ID and secret)."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"properties"),": This is a free form mapping of name and value strings. But Cogment may require properties of specific names for its operation, in particular for endpoint ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/parameters#cogment-endpoints"},"discovery"),". These special property names are prefixed with a double underscore (","_","_","), e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"__implementation"),". Also, for proper use in Cogment, property names and values should be restricted to a limited character set (see ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/parameters#discovery-query"},"endpoint query"),")."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"secret"),": This is a secret string that is generated by the Directory on registering a new service. It must be provided to deregister a service. There is no way to recover this value, so it must be recorded after registration."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"authentication token"),": A string to authenticate users of the registered service. It is provided by the user for registration of a new service, and the same token must be provided to access (deregister or inquire) that service.")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/50751b0a.5ac1ed00.js b/assets/js/50751b0a.5ac1ed00.js new file mode 100644 index 0000000..4384d8f --- /dev/null +++ b/assets/js/50751b0a.5ac1ed00.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkcogment_doc=self.webpackChunkcogment_doc||[]).push([[8687],{3905:(e,t,n)=>{n.d(t,{Zo:()=>d,kt:()=>m});var r=n(7294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function o(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var s=r.createContext({}),c=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):o(o({},t),e)),n},d=function(e){var t=c(e.components);return r.createElement(s.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},h=r.forwardRef((function(e,t){var n=e.components,i=e.mdxType,a=e.originalType,s=e.parentName,d=l(e,["components","mdxType","originalType","parentName"]),h=c(n),m=i,u=h["".concat(s,".").concat(m)]||h[m]||p[m]||a;return n?r.createElement(u,o(o({ref:t},d),{},{components:n})):r.createElement(u,o({ref:t},d))}));function m(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var a=n.length,o=new Array(a);o[0]=h;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:i,o[1]=l;for(var c=2;c{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>o,default:()=>p,frontMatter:()=>a,metadata:()=>l,toc:()=>c});var r=n(7462),i=(n(7294),n(3905));const a={title:"Server",sidebar_position:1},o="Directory Server",l={unversionedId:"reference/cli/directory/directory-server",id:"reference/cli/directory/directory-server",title:"Server",description:"The Directory is an implementation of the directory gRPC service. It is the service to find other services. Typically, every other Cogment service only needs to know the address of the Directory to access anything in Cogment.",source:"@site/docs/reference/cli/directory/directory-server.md",sourceDirName:"reference/cli/directory",slug:"/reference/cli/directory/directory-server",permalink:"/docs/reference/cli/directory/directory-server",draft:!1,tags:[],version:"current",lastUpdatedAt:1700230418,formattedLastUpdatedAt:"Nov 17, 2023",sidebarPosition:1,frontMatter:{title:"Server",sidebar_position:1},sidebar:"docSidebar",previous:{title:"Orchestrator",permalink:"/docs/reference/cli/orchestrator"},next:{title:"Client",permalink:"/docs/reference/cli/directory/directory-client"}},s={},c=[{value:"Command line",id:"command-line",level:2},{value:"Options",id:"options",level:2},{value:"port",id:"port",level:3},{value:"grpc_reflection",id:"grpc_reflection",level:3},{value:"log_level",id:"log_level",level:3},{value:"log_file",id:"log_file",level:3},{value:"registration_lag",id:"registration_lag",level:3},{value:"persistence_file",id:"persistence_file",level:3},{value:"load_balancing",id:"load_balancing",level:3},{value:"check_on_inquire",id:"check_on_inquire",level:3},{value:"force_permanent",id:"force_permanent",level:3},{value:"Operation",id:"operation",level:2},{value:"Health Checking",id:"health-checking",level:3},{value:"Load Balancing",id:"load-balancing",level:3},{value:"Data",id:"data",level:3}],d={toc:c};function p(e){let{components:t,...n}=e;return(0,i.kt)("wrapper",(0,r.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("h1",{id:"directory-server"},"Directory Server"),(0,i.kt)("p",null,"The Directory is an implementation of the ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/grpc#directory-api"},"directory gRPC service"),". It is the service to find other services. Typically, every other Cogment service only needs to know the address of the Directory to access anything in Cogment."),(0,i.kt)("p",null,"A regular health check is done on non-permanent network services to make sure they remain available (i.e. network reachable).\nIf a service fails the health check, it is automatically removed from the Directory."),(0,i.kt)("p",null,"The Directory works in tandem with the Cogment ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/parameters#cogment-endpoints"},"endpoints"),", in particular the ones with a ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/parameters#discover-host"},"discover host")," (referred as ",(0,i.kt)("strong",{parentName:"p"},"discovery endpoints"),")."),(0,i.kt)("p",null,"A ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/cli/directory/directory-client"},"Directory Client")," is also part of the Cogment CLI to access the Directory from the command line."),(0,i.kt)("h2",{id:"command-line"},"Command line"),(0,i.kt)("p",null,"The Directory is a Cogment CLI service:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"$ cogment services directory --port=9005\n")),(0,i.kt)("h2",{id:"options"},"Options"),(0,i.kt)("h3",{id:"port"},(0,i.kt)("inlineCode",{parentName:"h3"},"port")),(0,i.kt)("p",null,"The TCP port where to serve the ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/grpc#directory-api"},"directory gRPC service"),". This is where the users of the Directory connect to."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--port"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_PORT"),","),(0,i.kt)("li",{parentName:"ul"},"default value is 9005.")),(0,i.kt)("h3",{id:"grpc_reflection"},(0,i.kt)("inlineCode",{parentName:"h3"},"grpc_reflection")),(0,i.kt)("p",null,"Whether or not to enable ",(0,i.kt)("a",{parentName:"p",href:"https://github.com/grpc/grpc/blob/master/doc/server-reflection.md"},"gRPC reflection")," on the served directory endpoint."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--grpc_reflection"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_GRPC_REFLECTION=1"),","),(0,i.kt)("li",{parentName:"ul"},"by default, it is disabled.")),(0,i.kt)("h3",{id:"log_level"},(0,i.kt)("inlineCode",{parentName:"h3"},"log_level")),(0,i.kt)("p",null,"Set to define the minimum level for logging. Possible values are: ",(0,i.kt)("inlineCode",{parentName:"p"},"off"),", ",(0,i.kt)("inlineCode",{parentName:"p"},"error"),", ",(0,i.kt)("inlineCode",{parentName:"p"},"warning"),", ",(0,i.kt)("inlineCode",{parentName:"p"},"info"),", ",(0,i.kt)("inlineCode",{parentName:"p"},"debug"),", ",(0,i.kt)("inlineCode",{parentName:"p"},"trace"),"."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--log_level=debug"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_LOG_LEVEL=info"),","),(0,i.kt)("li",{parentName:"ul"},"default value is info.")),(0,i.kt)("h3",{id:"log_file"},(0,i.kt)("inlineCode",{parentName:"h3"},"log_file")),(0,i.kt)("p",null,"Base file name for daily log output. The name will be suffixed with the date and a new file will be made every day. If not provided, the logs go to stdout."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--log_file=./path/to/cogment.log"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_LOG_FILE=./path/to/cogment.log"),","),(0,i.kt)("li",{parentName:"ul"},"default value is info.")),(0,i.kt)("h3",{id:"registration_lag"},(0,i.kt)("inlineCode",{parentName:"h3"},"registration_lag")),(0,i.kt)("p",null,"The maximum number of seconds to wait before responding with no result (either due to a service not registered, or that has failed a health check).\nThis can be used when components may start at slightly different time, and some components may inquire about a component that did not have time to register yet.\nIt may also help when services sometimes go temporarily offline."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--registration_lag"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_REGISTRATION_LAG"),","),(0,i.kt)("li",{parentName:"ul"},"default value is 0.")),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},(0,i.kt)("a",{parentName:"p",href:"#load-balancing"},"Unserviceable"),' services are not considered for this lag.\nI.e. the directory will not wait for a service to become "serviceable".')),(0,i.kt)("h3",{id:"persistence_file"},(0,i.kt)("inlineCode",{parentName:"h3"},"persistence_file")),(0,i.kt)("p",null,"The file name where persistence data will be read from on start-up and stored afterward.\nThe file will be created if it does not already exist.\nIf set to an empty string, persistence will be disabled."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--persistence_file"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_PERSISTENCE_FILE"),","),(0,i.kt)("li",{parentName:"ul"},'default value is ".cogment-directory-data".')),(0,i.kt)("h3",{id:"load_balancing"},(0,i.kt)("inlineCode",{parentName:"h3"},"load_balancing")),(0,i.kt)("p",null,"Whether or not to enable ",(0,i.kt)("a",{parentName:"p",href:"#load-balancing"},"load balancing")," when services are inquired."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--load_balancing"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_LOAD_BALANCING=1"),","),(0,i.kt)("li",{parentName:"ul"},"by default, it is disabled.")),(0,i.kt)("h3",{id:"check_on_inquire"},(0,i.kt)("inlineCode",{parentName:"h3"},"check_on_inquire")),(0,i.kt)("p",null,"Whether or not to enable ",(0,i.kt)("a",{parentName:"p",href:"#health-checking"},"health checking")," when a service is matched by an inquiry (in addition to being checked periodically).\nThis can prevent unavailable services from being returned (before the periodic health check has time to run).\nIt can also allow load balancing to use more recent/dynamic values.\nBut it can significantly slow down directory inquiries, especially when a health check fails."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--check_on_inquire"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_CHECK_ON_INQUIRE=1"),","),(0,i.kt)("li",{parentName:"ul"},"by default, it is disabled.")),(0,i.kt)("h3",{id:"force_permanent"},(0,i.kt)("inlineCode",{parentName:"h3"},"force_permanent")),(0,i.kt)("p",null,"Forces all registration of services to be a ",(0,i.kt)("a",{parentName:"p",href:"#data"},"permanent")," entry."),(0,i.kt)("p",null,"Services can normally be tagged permanent on an individual basis.\nThis ",(0,i.kt)("inlineCode",{parentName:"p"},"force_permanent")," option is for special circumstances where ",(0,i.kt)("strong",{parentName:"p"},"all")," entries should be permanent and it is not appropriate, or too complicated, to set each individual entry to be permanent."),(0,i.kt)("p",null,"Permanent entries are not health checked, and thus are not implicitly removed from the Directory if they fail.\nThey are also not duplicated; they are updated instead of being duplicated or replaced."),(0,i.kt)("p",null,"Can be specified as:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"a command line option, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"--force_permanent"),","),(0,i.kt)("li",{parentName:"ul"},"an environment variable, e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"COGMENT_DIRECTORY_FORCE_PERMANENT=1"),","),(0,i.kt)("li",{parentName:"ul"},"by default, it is disabled.")),(0,i.kt)("h2",{id:"operation"},"Operation"),(0,i.kt)("p",null,"At its most basic, the Directory contains services searchable by type and property, and returns endpoints where to reach the matched services."),(0,i.kt)("p",null,'Every registered service has a unique ID (it is unique among currently registered services). When registering a service, the ID of the new service is provided with a "secret" key (a string).\nThis "secret" (in combination with the ID) is required to deregister the service.\nIf a new service matches an existing one (i.e. an inquiry would match them), it is considered a duplicate.\nDuplicates are acceptable for non-permanent services.\nFor permanent services (both the old and new services must be permanent), duplicates are not allowed; instead, an update of the old service is performed (i.e. the ID and secret are kept the same).'),(0,i.kt)("p",null,"Every service is also associated with an authentication token.\nThis token is provided by users when registering a new service, and it must be provided to inquire or deregister that service.\nFor example, any inquiry can only find services that have the same authentication token as the one provided to the inquiry.\nSimilarly for deregistering: a service cannot be deregistered without the appropriate authentication token.\nIn closed environments, the authentication token can be left empty to facilitate directory management."),(0,i.kt)("h3",{id:"health-checking"},"Health Checking"),(0,i.kt)("p",null,"Each entry is normally checked for connectivity on a regular basis (every 60 seconds), but can also be checked when an entry matches an inquiry (see ",(0,i.kt)("a",{parentName:"p",href:"#check_on_inquire"},"check_on_inquire"),")."),(0,i.kt)("p",null,"The type of the entry determines the extent of the health check.\nFor Cogment services, the ",(0,i.kt)("inlineCode",{parentName:"p"},"Status")," procedure will be called and a response expected.\nFor non-Cogment services, a simple tcp connection will be attempted, and if successful, the service will be considered healthy."),(0,i.kt)("p",null,"If a service fails the health check multiple times, it will be removed from the directory.\nBut after the first failure, the service will not be reported on inquiries until and unless it succeeds a health check."),(0,i.kt)("p",null,"When services are recovered from a persistence file, they will immediately be subjected to a health check."),(0,i.kt)("h3",{id:"load-balancing"},"Load Balancing"),(0,i.kt)("p",null,"By default load balancing is disabled, and thus when inquiring, the services returned are in increasing order of age (since registration).\nSo the first is always the most recently registered service."),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"Permanent services do not change their registration timestamp when updated.")),(0,i.kt)("p",null,"When load balancing is enabled, and an inquiry is made, the order of services returned is different:"),(0,i.kt)("ol",null,(0,i.kt)("li",{parentName:"ol"},'For each service that match the inquiry, the last read "overall_load" ',(0,i.kt)("inlineCode",{parentName:"li"},"Status")," (see below) is used. If ",(0,i.kt)("a",{parentName:"li",href:"#check_on_inquire"},"check_on_inquire"),' is enabled, then the service\'s current "overall_load" is read at this point.'),(0,i.kt)("li",{parentName:"ol"},"Services with a load of 255 are considered unserviceable and removed from the list of potential candidates."),(0,i.kt)("li",{parentName:"ol"},"The service with the lowest load is found. That service, and services with a load close to that one, are retained."),(0,i.kt)("li",{parentName:"ol"},"The retained services are shuffled randomly, and returned as a reply to the inquiry.")),(0,i.kt)("admonition",{type:"note"},(0,i.kt)("p",{parentName:"admonition"},"Non-Cogment services (with no ",(0,i.kt)("inlineCode",{parentName:"p"},"Status")," gRPC procedure) are always considered fully available (with a load of 0).\nAnd thus will always be returned, but in random order, when load balancing is enabled.")),(0,i.kt)("p",null,"The ",(0,i.kt)("inlineCode",{parentName:"p"},"Status"),' gRPC procedure\'s "overall_load" status is expected to be a string representation of an integer from 0 to 255 (8 bit unsigned integer).\nIf the string cannot be converted to such an integer, a load of 0 is assumed (e.g. "256" will result in a load of 0).\nA normal value is between 0 and 100, representing the load on the machine where the service is running.\nA value of 0 means that there is no load, and a value of 100 means that the machine is very loaded (and may not be able to do processing in a timely manner).\nThe exact meaning of the value is dependent on the service reporting.\nA value of 255 indicates that the machine is not fit to run any new service (and thus it is "unserviceable").'),(0,i.kt)("h3",{id:"data"},"Data"),(0,i.kt)("p",null,"The Directory maintains the following data for each service:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"service ID"),": This is a numerical (64 bits unsigned integer) value generated by the Directory and assigned to the service on registration. It is unique to that service as long as it is in the Directory. Although very unlikely, it is possible for this ID to be re-used after the service is deregistered. Zero (0) is not a valid ID."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"endpoint"),": It consists of four distinct information:",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"protocol: The protocol (URL scheme) for the endpoint (",(0,i.kt)("inlineCode",{parentName:"li"},"grpc")," or ",(0,i.kt)("inlineCode",{parentName:"li"},"cogment"),"). The ",(0,i.kt)("inlineCode",{parentName:"li"},"cogment"),' protocol is not considered a "network" protocol and thus will not be checked for health (network connectivity).'),(0,i.kt)("li",{parentName:"ul"},"host: The host for the endpoint (e.g. somewhere.com). For the ",(0,i.kt)("inlineCode",{parentName:"li"},"grpc")," protocol this represents a TCP/IP network resource; it can be a network hostname or an IP address. For the ",(0,i.kt)("inlineCode",{parentName:"li"},"cogment")," protocol it must be a registered name (see ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/parameters#cogment-endpoints"},"cogment endpoints"),") and typically does not represent a network resource."),(0,i.kt)("li",{parentName:"ul"},"port: The TCP port where the registered service is providing its services. This is required for ",(0,i.kt)("inlineCode",{parentName:"li"},"grpc")," protocol hosts."),(0,i.kt)("li",{parentName:"ul"},"ssl requirement: Whether the service requires an encrypted SSL connection."))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"type"),": The type of service. This also determines how health checks are performed on the service (i.e. which gRPC service should be used to check the health of the service).",(0,i.kt)("ul",{parentName:"li"},(0,i.kt)("li",{parentName:"ul"},"client actor connection: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-clientactorsp"},"client actor")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"trial lifecycle management: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-triallifecyclesp"},"lifecycle")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"actor: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-actor-api"},"actor")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"environment: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-environmentsp"},"environment")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"pre-hook: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-trialhookssp"},"pre-hook")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"datalog: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-logexportersp"},"datalog")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"datastore: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-trialdatastoresp"},"datastore")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"model registry: Provides ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/grpc#service-modelregistrysp"},"model registry")," gRPC API service"),(0,i.kt)("li",{parentName:"ul"},"other: This type of service does not provide a gRPC API service or it is not a type of service known to Cogment. Only the ability to perform a tcp connection will be tested for health checking."))),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"permanent"),": This determines if the service should be kept in the directory regardless of health (network connectivity). It also prevents duplication of the service in the directory (i.e. if a duplicate is registered, the service will just be updated with the new information, and keep the same ID and secret)."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"properties"),": This is a free form mapping of name and value strings. But Cogment may require properties of specific names for its operation, in particular for endpoint ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/parameters#cogment-endpoints"},"discovery"),". These special property names are prefixed with a double underscore (","_","_","), e.g. ",(0,i.kt)("inlineCode",{parentName:"li"},"__implementation"),". Also, for proper use in Cogment, property names and values should be restricted to a limited character set (see ",(0,i.kt)("a",{parentName:"li",href:"/docs/reference/parameters#discovery-query"},"endpoint query"),")."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"secret"),": This is a secret string that is generated by the Directory on registering a new service. It must be provided to deregister a service. There is no way to recover this value, so it must be recorded after registration."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("strong",{parentName:"li"},"authentication token"),": A string to authenticate users of the registered service. It is provided by the user for registration of a new service, and the same token must be provided to access (deregister or inquire) that service.")))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/8f51b104.3158977f.js b/assets/js/8f51b104.3158977f.js deleted file mode 100644 index 98caf4e..0000000 --- a/assets/js/8f51b104.3158977f.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkcogment_doc=self.webpackChunkcogment_doc||[]).push([[7330],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>h});var a=n(7294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function l(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var s=a.createContext({}),d=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},p=function(e){var t=d(e.components);return a.createElement(s.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},m=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,r=e.originalType,s=e.parentName,p=o(e,["components","mdxType","originalType","parentName"]),m=d(n),h=i,u=m["".concat(s,".").concat(h)]||m[h]||c[h]||r;return n?a.createElement(u,l(l({ref:t},p),{},{components:n})):a.createElement(u,l({ref:t},p))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=n.length,l=new Array(r);l[0]=m;var o={};for(var s in t)hasOwnProperty.call(t,s)&&(o[s]=t[s]);o.originalType=e,o.mdxType="string"==typeof e?e:i,l[1]=o;for(var d=2;d{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>l,default:()=>c,frontMatter:()=>r,metadata:()=>o,toc:()=>d});var a=n(7462),i=(n(7294),n(3905));const r={sidebar_position:5},l="Javascript SDK",o={unversionedId:"reference/javascript",id:"reference/javascript",title:"Javascript SDK",description:"Repository Latest release",source:"@site/docs/reference/javascript.md",sourceDirName:"reference",slug:"/reference/javascript",permalink:"/docs/reference/javascript",draft:!1,tags:[],version:"current",lastUpdatedAt:1664807199,formattedLastUpdatedAt:"Oct 3, 2022",sidebarPosition:5,frontMatter:{sidebar_position:5},sidebar:"docSidebar",previous:{title:"Python SDK",permalink:"/docs/reference/python"},next:{title:"Installation",permalink:"/docs/reference/python-enterprise/installation"}},s={},d=[{value:"Installation",id:"installation",level:2},{value:"General usage",id:"general-usage",level:2},{value:"The spec file",id:"the-spec-file",level:3},{value:"Trial Parameters",id:"trial-parameters",level:3},{value:"Compiling the spec file",id:"compiling-the-spec-file",level:4},{value:"CogSettings.js",id:"cogsettingsjs",level:3},{value:"Imports",id:"imports",level:3},{value:"class cogment.Context",id:"class-cogmentcontext",level:2},{value:"constructor(userId, cogSettings)",id:"constructoruserid-cogsettings",level:3},{value:"getController(endpoint)",id:"getcontrollerendpoint",level:3},{value:"async joinTrial(trialId, endpoint, actorName)",id:"async-jointrialtrialid-endpoint-actorname",level:3},{value:"registerActor(impl, actorName, actorClass)",id:"registeractorimpl-actorname-actorclass",level:3},{value:"class Controller",id:"class-controller",level:2},{value:"async startTrial(trialConfig = undefined, trialIdRequested = undefined)",id:"async-starttrialtrialconfig--undefined-trialidrequested--undefined",level:3},{value:"terminateTrial(trialIds, hard = false)",id:"terminatetrialtrialids-hard--false",level:3},{value:"async getTrialInfo(trialIds)",id:"async-gettrialinfotrialids",level:3},{value:"async watchTrials(trialStateFilters=[])",id:"async-watchtrialstrialstatefilters",level:3},{value:"async getActors(trialId)",id:"async-getactorstrialid",level:3},{value:"async getRemoteVersions()",id:"async-getremoteversions",level:3},{value:"class Session",id:"class-session",level:2},{value:"getTrialId()",id:"gettrialid",level:3},{value:"getTickId()",id:"gettickid",level:3},{value:"isTrialOver()",id:"istrialover",level:3},{value:"sendingDone()",id:"sendingdone",level:3},{value:"class ActorSession extends Session",id:"class-actorsession-extends-session",level:2},{value:"start(autoDoneSending=True)",id:"startautodonesendingtrue",level:3},{value:"async *eventLoop()",id:"async-eventloop",level:3},{value:"doAction(action)",id:"doactionaction",level:3},{value:"sendMessage(payload, to)",id:"sendmessagepayload-to",level:3},{value:"enum cogment.TrialState",id:"enum-cogmenttrialstate",level:2},{value:"class TrialInfo",id:"class-trialinfo",level:2},{value:"class RecvEvent",id:"class-recvevent",level:2},{value:"enum cogment.EventType",id:"enum-cogmenteventtype",level:3},{value:"type ObservationT",id:"type-observationt",level:2},{value:"type ActionT",id:"type-actiont",level:2},{value:"class MessageBase",id:"class-messagebase",level:2},{value:"type Reward",id:"type-reward",level:2},{value:"interface IRewardSource",id:"interface-irewardsource",level:2}],p={toc:d};function c(e){let{components:t,...n}=e;return(0,i.kt)("wrapper",(0,a.Z)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("h1",{id:"javascript-sdk"},"Javascript SDK"),(0,i.kt)("p",null,(0,i.kt)("a",{parentName:"p",href:"https://github.com/cogment/cogment-js-sdk"},(0,i.kt)("img",{parentName:"a",src:"https://img.shields.io/badge/repository-cogment%2Fcogment--js--sdk-%235217b8?style=for-the-badge&logo=github",alt:"Repository"}))," ",(0,i.kt)("a",{parentName:"p",href:"https://www.npmjs.com/package/@cogment/cogment-js-sdk"},(0,i.kt)("img",{parentName:"a",src:"https://img.shields.io/npm/v/@cogment/cogment-js-sdk?style=for-the-badge",alt:"Latest release"}))),(0,i.kt)("h2",{id:"installation"},"Installation"),(0,i.kt)("p",null,"The simplest way to install the Javascript SDK is to just install it using npm:\n",(0,i.kt)("inlineCode",{parentName:"p"},"npm install @cogment/cogment-js-sdk")),(0,i.kt)("h2",{id:"general-usage"},"General usage"),(0,i.kt)("h3",{id:"the-spec-file"},"The spec file"),(0,i.kt)("p",null,"The specifications of a trial type are contained in a ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/cogment-yaml"},"spec file")," and the imported files defined in the spec. This file is typically named ",(0,i.kt)("inlineCode",{parentName:"p"},"cogment.yaml"),"."),(0,i.kt)("p",null,"For example, an ",(0,i.kt)("a",{parentName:"p",href:"/docs/guide/core-concepts#actors"},"actor")," class is defined by its required observation space and action space."),(0,i.kt)("p",null,'These "spaces" are defined by using protobuf message types (from the imported files). ',(0,i.kt)("a",{parentName:"p",href:"/docs/guide/core-concepts#observations--actions"},"Observations and actions")," will simply be instances of the appropriate type."),(0,i.kt)("p",null,"Messages and feedback user data don't have a set type, they can be any type as long as the receiver can manage that type. The type is determined by the provided message from the originator."),(0,i.kt)("p",null,"They will mostly arrive as an instance of ",(0,i.kt)("inlineCode",{parentName:"p"},"cogment.MessageBase")," and have fields according to their definition in your proto files."),(0,i.kt)("h3",{id:"trial-parameters"},"Trial Parameters"),(0,i.kt)("p",null,"The trial ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/parameters"},"parameters")," can come from the default parameters provided to the Orchestrator on startup, or from the pre-trial hooks (themselves provided to the Orchestrator on startup)."),(0,i.kt)("p",null,"The parameters are mostly indepedent of the spec file (cogment.yaml), except that the active actors listed in the parameters must have their actor class match an actor class defined in the spec file."),(0,i.kt)("p",null,"Below, when we refer to the trial parameters, we mean the final parameters after any pre-trial hooks."),(0,i.kt)("h4",{id:"compiling-the-spec-file"},"Compiling the spec file"),(0,i.kt)("p",null,'In order to use the specification found in the spec file within Javascript scripts, it needs to be compiled into Javascript modules. This is done by a tool called "cogment-js-sdk-generate".'),(0,i.kt)("h3",{id:"cogsettingsjs"},"CogSettings.js"),(0,i.kt)("p",null,"All API entry points require a cogment specification object. This specification object can be determined\nfrom the content of a project's spec file. As such, it should be generated using the ",(0,i.kt)("inlineCode",{parentName:"p"},"cogment-js-sdk-generate")," tool"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre"},"npx cogment-js-sdk-generate config.yaml\n")),(0,i.kt)("p",null,"This will generate both a ",(0,i.kt)("inlineCode",{parentName:"p"},"CogSettings.js")," file, as well as any required compiled protocol buffer files."),(0,i.kt)("h3",{id:"imports"},"Imports"),(0,i.kt)("p",null,"Whether a script implements an actor or environment, it should import both the ",(0,i.kt)("inlineCode",{parentName:"p"},"cogment")," module (generic Javascript SDK for Cogment) and the ",(0,i.kt)("inlineCode",{parentName:"p"},"cogSettings")," module (project specific definitions created from the spec file)."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-Javascript"},"import { cogSettings } from './CogSettings';\nimport * as cogment from '@cogment/cogment-js-sdk'\n")),(0,i.kt)("h2",{id:"class-cogmentcontext"},"class cogment.Context"),(0,i.kt)("p",null,"Class to setup and run all the different aspects of trials."),(0,i.kt)("h3",{id:"constructoruserid-cogsettings"},(0,i.kt)("inlineCode",{parentName:"h3"},"constructor(userId, cogSettings)")),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"userId"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - Identifier for the user of this context."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"cogSettings"),": ",(0,i.kt)("em",{parentName:"li"},"cogment.CogSettings")," - Settings module associated with trials that will be run (",(0,i.kt)("a",{parentName:"li",href:"#cog_settings.py"},"cogSettings")," namespace).")),(0,i.kt)("h3",{id:"getcontrollerendpoint"},(0,i.kt)("inlineCode",{parentName:"h3"},"getController(endpoint)")),(0,i.kt)("p",null,"Method to get a controller instance to manage trials (start, stop, inquire, etc)."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"endpoint"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - URL of the connection to the Orchestrator.")),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"Controller")," - An instance of the Controller class used to manage trials."),(0,i.kt)("h3",{id:"async-jointrialtrialid-endpoint-actorname"},(0,i.kt)("inlineCode",{parentName:"h3"},"async joinTrial(trialId, endpoint, actorName)")),(0,i.kt)("p",null,"Method for an actor to asynchronously join an existing trial. This task will normally end after the user implementation has exited."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialId"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - The UUID of the trial to join."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"endpoint"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - URL of the connection to the Orchestrator."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"actorName"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - Name of the actor joining the trial.")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h3",{id:"registeractorimpl-actorname-actorclass"},(0,i.kt)("inlineCode",{parentName:"h3"},"registerActor(impl, actorName, actorClass)")),(0,i.kt)("p",null,"Method to register the asynchronous callback function that will run an actor for a trial."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"impl"),": ",(0,i.kt)("em",{parentName:"li"},"async function(ActorSession instance)")," - Callback function to be registered."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"actorName"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - Name for the actor implementation being run by the given callback function."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"actorClass"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - The actor class name that can be run by the given callback function. The possible names are specified in spec file under section ",(0,i.kt)("inlineCode",{parentName:"li"},"actorClasses:name"),". If the list is empty, this implementation can run any actor class.")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h2",{id:"class-controller"},"class Controller"),(0,i.kt)("p",null,"Class containing data and methods to control and manage trials."),(0,i.kt)("h3",{id:"async-starttrialtrialconfig--undefined-trialidrequested--undefined"},(0,i.kt)("inlineCode",{parentName:"h3"},"async startTrial(trialConfig = undefined, trialIdRequested = undefined)")),(0,i.kt)("p",null,"Method to start a new trial. The parameters of the trial will be set by the pre-trial hooks (registered in ",(0,i.kt)("inlineCode",{parentName:"p"},"cogment.Context"),"), and the hooks will receive the provided trial config."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialConfig"),": ",(0,i.kt)("em",{parentName:"li"},"cogment.MessageBase")," - Configuration for the trial. The type is specified in the spec file under the section ",(0,i.kt)("inlineCode",{parentName:"li"},"trial:config_type"),". Can be ",(0,i.kt)("inlineCode",{parentName:"li"},"undefined")," if no configuration is provided. This is provided to the first pre-trial hook."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialIdRequested"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - The trial identifier requested for the new trial. It must be unique among all active trials and a limited set of the latest ended trials (this list of trials can be retrieved with ",(0,i.kt)("inlineCode",{parentName:"li"},"getTrialInfo")," or ",(0,i.kt)("inlineCode",{parentName:"li"},"watchTrial"),"). If provided, the Orchestrator will try to use this trialId, otherwise, a UUID will be created.")),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"string")," - The newly started trial ID."),(0,i.kt)("h3",{id:"terminatetrialtrialids-hard--false"},(0,i.kt)("inlineCode",{parentName:"h3"},"terminateTrial(trialIds, hard = false)")),(0,i.kt)("p",null,"Method to request the end of a trial."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialIds"),": ",(0,i.kt)("em",{parentName:"li"},"string[]")," - The trial ID(s) to request to terminate. There must be at least one ID."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"hard"),": ",(0,i.kt)("em",{parentName:"li"},"boolean")," - If ",(0,i.kt)("inlineCode",{parentName:"li"},"true"),", the termination will be forced and not wait for any action or observation. If ",(0,i.kt)("inlineCode",{parentName:"li"},"false"),", the trial will wait for the next tick, to end gracefully (i.e. wait for the next full set of actions and response observations).")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h3",{id:"async-gettrialinfotrialids"},(0,i.kt)("inlineCode",{parentName:"h3"},"async getTrialInfo(trialIds)")),(0,i.kt)("p",null,"Method to get information about a trial."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialIds"),": ",(0,i.kt)("em",{parentName:"li"},"string[]")," - The trial ID(s) from which to request information. If no ID is provided, returns information about all trials. Note that ended trials may only appear for a short time in this list after they have ended.")),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"TrialInfo[]")," - List of trial information, one per trial. Can be empty if no trial matches."),(0,i.kt)("h3",{id:"async-watchtrialstrialstatefilters"},(0,i.kt)("inlineCode",{parentName:"h3"},"async watchTrials(trialStateFilters=[])")),(0,i.kt)("p",null,"Generator method to iterate, in real-time, through all trial states matching the filters. When called, it will first iterate over the current states matching the filters, for all trials. Afterwards, it will iterate in real-time over the matching states as they change."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialStateFilters"),": ",(0,i.kt)("em",{parentName:"li"},"cogment.TrialState[]")," - List of enum values from ",(0,i.kt)("inlineCode",{parentName:"li"},"cogment.TrialState")," for which we are interested in receiving state changes.")),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"generator(TrialInfo instance)")," - A generator for the state changes that arrive. The ",(0,i.kt)("inlineCode",{parentName:"p"},"TrialInfo")," received here only contains the trial ID and the state."),(0,i.kt)("h3",{id:"async-getactorstrialid"},(0,i.kt)("inlineCode",{parentName:"h3"},"async getActors(trialId)")),(0,i.kt)("p",null,"Method to get the list of configured actors in a trial."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialId"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - The trial ID from which to request the list of actors.")),(0,i.kt)("p",null,"Return: ActorInfo[] - List of actors configured in this trial."),(0,i.kt)("h3",{id:"async-getremoteversions"},(0,i.kt)("inlineCode",{parentName:"h3"},"async getRemoteVersions()")),(0,i.kt)("p",null,"Method to get the versions from the remote Orchestrator."),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"{","[key: string]",": string}")," - The key of the object is the name of the component (",(0,i.kt)("em",{parentName:"p"},"string"),"), and the value is the version (",(0,i.kt)("em",{parentName:"p"},"string"),")."),(0,i.kt)("h2",{id:"class-session"},"class Session"),(0,i.kt)("p",null,"Abstract class that manages aspects of a trial. Contains data and methods common to all sessions ."),(0,i.kt)("h3",{id:"gettrialid"},(0,i.kt)("inlineCode",{parentName:"h3"},"getTrialId()")),(0,i.kt)("p",null,"Method to get the UUID of the trial managed by this session."),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"string")," - UUID of the trial."),(0,i.kt)("h3",{id:"gettickid"},(0,i.kt)("inlineCode",{parentName:"h3"},"getTickId()")),(0,i.kt)("p",null,"Method to get the current tick id of the trial (i.e. time step)."),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"number")," - The current tick id."),(0,i.kt)("h3",{id:"istrialover"},(0,i.kt)("inlineCode",{parentName:"h3"},"isTrialOver()")),(0,i.kt)("p",null,"Method to inquire if the current trial has ended."),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"boolean")," - True if the trial has ended, false otherwise."),(0,i.kt)("h3",{id:"sendingdone"},(0,i.kt)("inlineCode",{parentName:"h3"},"sendingDone()")),(0,i.kt)("p",null,"Method to notify the Orchestrator that all data for the trial, from this session, has been sent. This can be called only when the session is ending. When starting the session (see ",(0,i.kt)("inlineCode",{parentName:"p"},"ActorSession"),"), if the ",(0,i.kt)("inlineCode",{parentName:"p"},"autoDoneSending")," parameter is True, this method should not be called, and if the parameter is False, it MUST be called to end the trial properly."),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h2",{id:"class-actorsession-extends-session"},"class ActorSession extends Session"),(0,i.kt)("h3",{id:"startautodonesendingtrue"},(0,i.kt)("inlineCode",{parentName:"h3"},"start(autoDoneSending=True)")),(0,i.kt)("p",null,"Method to start the actor. This method should be called before any other method in the session."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"autoDoneSending"),": ",(0,i.kt)("em",{parentName:"li"},"boolean")," - Controls when to notify the Orchestrator that all data has been sent. If True, the session will automatically send the notification after receiving the last observation. If False, the user MUST call ",(0,i.kt)("inlineCode",{parentName:"li"},"sendingDone")," to end the trial properly.")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h3",{id:"async-eventloop"},(0,i.kt)("inlineCode",{parentName:"h3"},"async *eventLoop()")),(0,i.kt)("p",null,"Generator method to iterate over all events (observations, rewards, messages) as they are received. This will block and wait for an event.\nWhen this generator exits, the callback function (registered with ",(0,i.kt)("inlineCode",{parentName:"p"},"registerActor"),') should return to end the trial cleanly.\nThe generator will exit for various reasons indicating the end of the trial, a loss of communication with the orchestrator, or if the generator is sent "False".'),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"AsyncGenerator")," - A generator for the events that arrive. The ",(0,i.kt)("inlineCode",{parentName:"p"},"RecvEvent")," instances received from this generator will not contain actions. When receiving an observation in the event, the ",(0,i.kt)("inlineCode",{parentName:"p"},"this.doAction"),' method is normally used to "reply" (if the event type is ',(0,i.kt)("inlineCode",{parentName:"p"},"EventType.ACTIVE"),")."),(0,i.kt)("h3",{id:"doactionaction"},(0,i.kt)("inlineCode",{parentName:"h3"},"doAction(action)")),(0,i.kt)("p",null,"Method to send actions to the environment."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"action"),": ",(0,i.kt)("em",{parentName:"li"},"ActionT")," - An instance of the action space class specified in the corresponding section ",(0,i.kt)("inlineCode",{parentName:"li"},"actorClasses:action:space")," of the spec file. If ",(0,i.kt)("inlineCode",{parentName:"li"},"undefined"),", then no action space is sent (empty content) and the environment will receive a default initialized action space of the appropriate type.")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h3",{id:"sendmessagepayload-to"},(0,i.kt)("inlineCode",{parentName:"h3"},"sendMessage(payload, to)")),(0,i.kt)("p",null,"Method to send a message related to the current time step (tick id)."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"payload"),": ",(0,i.kt)("em",{parentName:"li"},"cogment.MessageBase")," - The message data to be sent. The class can be any protobuf class. It is the responsibility of the receiving actor to manage the class received."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"to"),": ",(0,i.kt)("em",{parentName:"li"},"string[]")," - Targets of feedback. Each value could be the name of an actor in the trial, or the name of the environment (from ",(0,i.kt)("inlineCode",{parentName:"li"},"this.envName"),'). Or it could represent a set of actors (with wildcards); A set of actors can be represented with the wildcard character "',(0,i.kt)("inlineCode",{parentName:"li"},"*"),'" for all actors (of all classes), or "',(0,i.kt)("inlineCode",{parentName:"li"},"actorClass.*"),'" for all actors of a specific class (the ',(0,i.kt)("inlineCode",{parentName:"li"},"actorClass")," must match one of the classes listed in the trial parameters). Note that the wildcard does not include the environment.")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h2",{id:"enum-cogmenttrialstate"},"enum cogment.TrialState"),(0,i.kt)("p",null,"Enum representing the various states of trials."),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"UNKNOWN: Should not be used."),(0,i.kt)("li",{parentName:"ul"},"INITIALIZING: The trial is in the process of starting."),(0,i.kt)("li",{parentName:"ul"},"PENDING: The trial is waiting for its final parameters, before running."),(0,i.kt)("li",{parentName:"ul"},"RUNNING: The trial is running."),(0,i.kt)("li",{parentName:"ul"},"TERMINATING: The trial is in the process of terminating (either a request to terminate has been received or the last observation has been received)."),(0,i.kt)("li",{parentName:"ul"},"ENDED: The trial has ended. Only a set number of ended trials will be kept (configured in the Orchestrator).")),(0,i.kt)("p",null,"For further information on trial lifetime, check the ",(0,i.kt)("a",{parentName:"p",href:"/docs/guide/development-guide#trial-lifetime"},"dedicated section"),"."),(0,i.kt)("h2",{id:"class-trialinfo"},"class TrialInfo"),(0,i.kt)("p",null,"Class enclosing the details of a trial."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"trialId"),": ",(0,i.kt)("em",{parentName:"p"},"string")," - The trial ID to which the details pertain."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"state"),": ",(0,i.kt)("em",{parentName:"p"},"cogment.TrialState")," - The current state of the trial."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"envName"),": ",(0,i.kt)("em",{parentName:"p"},"string")," - The name of the environment running the trial."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"tickId"),": ",(0,i.kt)("em",{parentName:"p"},"number")," - The time step that the information relates to. Only provided from a call to ",(0,i.kt)("inlineCode",{parentName:"p"},"getTrialInfo"),"."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"duration"),": ",(0,i.kt)("em",{parentName:"p"},"number")," - The time (in nanoseconds) that the trial has run. Only provided from a call to ",(0,i.kt)("inlineCode",{parentName:"p"},"getTrialInfo"),"."),(0,i.kt)("h2",{id:"class-recvevent"},"class RecvEvent"),(0,i.kt)("p",null,"Class representing a received event (for environments and actors). It can contain any combination of data according to the receiver needs, or even be empty, but it will always have a type."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"type"),": ",(0,i.kt)("em",{parentName:"p"},"EventType")," - Type of event the enclosed data represents."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"observation"),": ",(0,i.kt)("em",{parentName:"p"},"ObservationT")," - Observation data. This can only be received by actors. ",(0,i.kt)("inlineCode",{parentName:"p"},"undefined")," if not present."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"actions"),": ",(0,i.kt)("em",{parentName:"p"},"ActionT")," - Action data from actors. This can only be received by the environment. The list is empty if not present."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"rewards"),": ",(0,i.kt)("em",{parentName:"p"},"Reward[]")," - Reward values and data. This can only be received by actors. The list is empty if not present."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"messages"),": ",(0,i.kt)("em",{parentName:"p"},"MessageBase[]")," - Message data. The list is empty if not present."),(0,i.kt)("h3",{id:"enum-cogmenteventtype"},"enum cogment.EventType"),(0,i.kt)("p",null,"Enum representing the type of an event."),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("inlineCode",{parentName:"p"},"EventType.NONE"),": Empty event. This kind of event should never be received.")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("inlineCode",{parentName:"p"},"EventType.ACTIVE"),": Normal event from an active trial. Most events will be of this type.")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("inlineCode",{parentName:"p"},"EventType.ENDING"),": Events from a trial in the process of ending. For the environment, this means that these events contain the last actions from the actors, and the trial is awaiting a final observation. For the actors, this means that the trial is ending and no action can/need to be sent in response. Note that because of network timing, there may be ",(0,i.kt)("inlineCode",{parentName:"p"},"ACTIVE")," events (e.g. rewards or messages) arriving after some ",(0,i.kt)("inlineCode",{parentName:"p"},"ENDING")," events, but the trial is ending regardless.")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("inlineCode",{parentName:"p"},"EventType.FINAL"),": Final event for the trial. This does not contain data. The event loop will exit after this event is delivered. This event can be ignored if nothing needs to be done before exiting the loop."))),(0,i.kt)("p",null,"For further information on trial lifetime, check the ",(0,i.kt)("a",{parentName:"p",href:"/docs/guide/development-guide#trial-lifetime"},"dedicated section"),"."),(0,i.kt)("h2",{id:"type-observationt"},"type ObservationT"),(0,i.kt)("p",null,"Type containing the details of an actor's observation. This will be different depending on what the ActionSpace defined in your spec file contains"),(0,i.kt)("h2",{id:"type-actiont"},"type ActionT"),(0,i.kt)("p",null,"Type containing the details of an action from an actor. This will be different depending on what the ActionSpace defined in your spec file contains"),(0,i.kt)("h2",{id:"class-messagebase"},"class MessageBase"),(0,i.kt)("p",null,"Base Class of all messages, this will contain different fields depending on what fields are in the specific message you are receiving (defined in proto files)"),(0,i.kt)("h2",{id:"type-reward"},"type Reward"),(0,i.kt)("p",null,"type containing the details of a received reward."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"tickId"),": ",(0,i.kt)("em",{parentName:"p"},"number")," - The tick id (time step) for which the reward should be applied."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"receiverName"),": ",(0,i.kt)("em",{parentName:"p"},"string")," - Name of the receiver for the reward (the name of an actor, or wildcard string)."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"value"),": ",(0,i.kt)("em",{parentName:"p"},"float")," - Value of the reward (aggregated from the sources)"),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"sources"),": ",(0,i.kt)("em",{parentName:"p"},"IRewardSource[]")," - List of sources that gave this reward"),(0,i.kt)("h2",{id:"interface-irewardsource"},"interface IRewardSource"),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"senderName"),": ",(0,i.kt)("em",{parentName:"p"},"string")," - Name of the reward sender;"),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"value"),": ",(0,i.kt)("em",{parentName:"p"},"number")," - Value of the reward;"),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"confidence"),": ",(0,i.kt)("em",{parentName:"p"},"number")," - Confidence of this reward;"),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"userData"),": ",(0,i.kt)("em",{parentName:"p"},"google.protobuf.IAny")," - Extra data;"))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/8f51b104.a7e302fa.js b/assets/js/8f51b104.a7e302fa.js new file mode 100644 index 0000000..fe893ed --- /dev/null +++ b/assets/js/8f51b104.a7e302fa.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkcogment_doc=self.webpackChunkcogment_doc||[]).push([[7330],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>h});var a=n(7294);function i(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function l(e){for(var t=1;t=0||(i[n]=e[n]);return i}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(i[n]=e[n])}return i}var s=a.createContext({}),d=function(e){var t=a.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):l(l({},t),e)),n},p=function(e){var t=d(e.components);return a.createElement(s.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},m=a.forwardRef((function(e,t){var n=e.components,i=e.mdxType,r=e.originalType,s=e.parentName,p=o(e,["components","mdxType","originalType","parentName"]),m=d(n),h=i,u=m["".concat(s,".").concat(h)]||m[h]||c[h]||r;return n?a.createElement(u,l(l({ref:t},p),{},{components:n})):a.createElement(u,l({ref:t},p))}));function h(e,t){var n=arguments,i=t&&t.mdxType;if("string"==typeof e||i){var r=n.length,l=new Array(r);l[0]=m;var o={};for(var s in t)hasOwnProperty.call(t,s)&&(o[s]=t[s]);o.originalType=e,o.mdxType="string"==typeof e?e:i,l[1]=o;for(var d=2;d{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>l,default:()=>c,frontMatter:()=>r,metadata:()=>o,toc:()=>d});var a=n(7462),i=(n(7294),n(3905));const r={sidebar_position:5},l="Javascript SDK",o={unversionedId:"reference/javascript",id:"reference/javascript",title:"Javascript SDK",description:"Repository Latest release",source:"@site/docs/reference/javascript.md",sourceDirName:"reference",slug:"/reference/javascript",permalink:"/docs/reference/javascript",draft:!1,tags:[],version:"current",lastUpdatedAt:1665585711,formattedLastUpdatedAt:"Oct 12, 2022",sidebarPosition:5,frontMatter:{sidebar_position:5},sidebar:"docSidebar",previous:{title:"Python SDK",permalink:"/docs/reference/python"},next:{title:"Installation",permalink:"/docs/reference/python-enterprise/installation"}},s={},d=[{value:"Installation",id:"installation",level:2},{value:"General usage",id:"general-usage",level:2},{value:"The spec file",id:"the-spec-file",level:3},{value:"Trial Parameters",id:"trial-parameters",level:3},{value:"Compiling the spec file",id:"compiling-the-spec-file",level:4},{value:"CogSettings.js",id:"cogsettingsjs",level:3},{value:"Imports",id:"imports",level:3},{value:"class cogment.Context",id:"class-cogmentcontext",level:2},{value:"constructor(userId, cogSettings)",id:"constructoruserid-cogsettings",level:3},{value:"getController(endpoint)",id:"getcontrollerendpoint",level:3},{value:"async joinTrial(trialId, endpoint, actorName)",id:"async-jointrialtrialid-endpoint-actorname",level:3},{value:"registerActor(impl, actorName, actorClass)",id:"registeractorimpl-actorname-actorclass",level:3},{value:"class Controller",id:"class-controller",level:2},{value:"async startTrial(trialConfig = undefined, trialIdRequested = undefined)",id:"async-starttrialtrialconfig--undefined-trialidrequested--undefined",level:3},{value:"terminateTrial(trialIds, hard = false)",id:"terminatetrialtrialids-hard--false",level:3},{value:"async getTrialInfo(trialIds)",id:"async-gettrialinfotrialids",level:3},{value:"async watchTrials(trialStateFilters=[])",id:"async-watchtrialstrialstatefilters",level:3},{value:"async getActors(trialId)",id:"async-getactorstrialid",level:3},{value:"async getRemoteVersions()",id:"async-getremoteversions",level:3},{value:"class Session",id:"class-session",level:2},{value:"getTrialId()",id:"gettrialid",level:3},{value:"getTickId()",id:"gettickid",level:3},{value:"isTrialOver()",id:"istrialover",level:3},{value:"sendingDone()",id:"sendingdone",level:3},{value:"class ActorSession extends Session",id:"class-actorsession-extends-session",level:2},{value:"start(autoDoneSending=True)",id:"startautodonesendingtrue",level:3},{value:"async *eventLoop()",id:"async-eventloop",level:3},{value:"doAction(action)",id:"doactionaction",level:3},{value:"sendMessage(payload, to)",id:"sendmessagepayload-to",level:3},{value:"enum cogment.TrialState",id:"enum-cogmenttrialstate",level:2},{value:"class TrialInfo",id:"class-trialinfo",level:2},{value:"class RecvEvent",id:"class-recvevent",level:2},{value:"enum cogment.EventType",id:"enum-cogmenteventtype",level:3},{value:"type ObservationT",id:"type-observationt",level:2},{value:"type ActionT",id:"type-actiont",level:2},{value:"class MessageBase",id:"class-messagebase",level:2},{value:"type Reward",id:"type-reward",level:2},{value:"interface IRewardSource",id:"interface-irewardsource",level:2}],p={toc:d};function c(e){let{components:t,...n}=e;return(0,i.kt)("wrapper",(0,a.Z)({},p,n,{components:t,mdxType:"MDXLayout"}),(0,i.kt)("h1",{id:"javascript-sdk"},"Javascript SDK"),(0,i.kt)("p",null,(0,i.kt)("a",{parentName:"p",href:"https://github.com/cogment/cogment-js-sdk"},(0,i.kt)("img",{parentName:"a",src:"https://img.shields.io/badge/repository-cogment%2Fcogment--js--sdk-%235217b8?style=for-the-badge&logo=github",alt:"Repository"}))," ",(0,i.kt)("a",{parentName:"p",href:"https://www.npmjs.com/package/@cogment/cogment-js-sdk"},(0,i.kt)("img",{parentName:"a",src:"https://img.shields.io/npm/v/@cogment/cogment-js-sdk?style=for-the-badge",alt:"Latest release"}))),(0,i.kt)("h2",{id:"installation"},"Installation"),(0,i.kt)("p",null,"The simplest way to install the Javascript SDK is to just install it using npm:\n",(0,i.kt)("inlineCode",{parentName:"p"},"npm install @cogment/cogment-js-sdk")),(0,i.kt)("h2",{id:"general-usage"},"General usage"),(0,i.kt)("h3",{id:"the-spec-file"},"The spec file"),(0,i.kt)("p",null,"The specifications of a trial type are contained in a ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/cogment-yaml"},"spec file")," and the imported files defined in the spec. This file is typically named ",(0,i.kt)("inlineCode",{parentName:"p"},"cogment.yaml"),"."),(0,i.kt)("p",null,"For example, an ",(0,i.kt)("a",{parentName:"p",href:"/docs/guide/core-concepts#actors"},"actor")," class is defined by its required observation space and action space."),(0,i.kt)("p",null,'These "spaces" are defined by using protobuf message types (from the imported files). ',(0,i.kt)("a",{parentName:"p",href:"/docs/guide/core-concepts#observations--actions"},"Observations and actions")," will simply be instances of the appropriate type."),(0,i.kt)("p",null,"Messages and feedback user data don't have a set type, they can be any type as long as the receiver can manage that type. The type is determined by the provided message from the originator."),(0,i.kt)("p",null,"They will mostly arrive as an instance of ",(0,i.kt)("inlineCode",{parentName:"p"},"cogment.MessageBase")," and have fields according to their definition in your proto files."),(0,i.kt)("h3",{id:"trial-parameters"},"Trial Parameters"),(0,i.kt)("p",null,"The trial ",(0,i.kt)("a",{parentName:"p",href:"/docs/reference/parameters"},"parameters")," can come from the default parameters provided to the Orchestrator on startup, or from the pre-trial hooks (themselves provided to the Orchestrator on startup)."),(0,i.kt)("p",null,"The parameters are mostly indepedent of the spec file (cogment.yaml), except that the active actors listed in the parameters must have their actor class match an actor class defined in the spec file."),(0,i.kt)("p",null,"Below, when we refer to the trial parameters, we mean the final parameters after any pre-trial hooks."),(0,i.kt)("h4",{id:"compiling-the-spec-file"},"Compiling the spec file"),(0,i.kt)("p",null,'In order to use the specification found in the spec file within Javascript scripts, it needs to be compiled into Javascript modules. This is done by a tool called "cogment-js-sdk-generate".'),(0,i.kt)("h3",{id:"cogsettingsjs"},"CogSettings.js"),(0,i.kt)("p",null,"All API entry points require a cogment specification object. This specification object can be determined\nfrom the content of a project's spec file. As such, it should be generated using the ",(0,i.kt)("inlineCode",{parentName:"p"},"cogment-js-sdk-generate")," tool"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre"},"npx cogment-js-sdk-generate config.yaml\n")),(0,i.kt)("p",null,"This will generate both a ",(0,i.kt)("inlineCode",{parentName:"p"},"CogSettings.js")," file, as well as any required compiled protocol buffer files."),(0,i.kt)("h3",{id:"imports"},"Imports"),(0,i.kt)("p",null,"Whether a script implements an actor or environment, it should import both the ",(0,i.kt)("inlineCode",{parentName:"p"},"cogment")," module (generic Javascript SDK for Cogment) and the ",(0,i.kt)("inlineCode",{parentName:"p"},"cogSettings")," module (project specific definitions created from the spec file)."),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-Javascript"},"import { cogSettings } from './CogSettings';\nimport * as cogment from '@cogment/cogment-js-sdk'\n")),(0,i.kt)("h2",{id:"class-cogmentcontext"},"class cogment.Context"),(0,i.kt)("p",null,"Class to setup and run all the different aspects of trials."),(0,i.kt)("h3",{id:"constructoruserid-cogsettings"},(0,i.kt)("inlineCode",{parentName:"h3"},"constructor(userId, cogSettings)")),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"userId"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - Identifier for the user of this context."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"cogSettings"),": ",(0,i.kt)("em",{parentName:"li"},"cogment.CogSettings")," - Settings module associated with trials that will be run (",(0,i.kt)("a",{parentName:"li",href:"#cog_settings.py"},"cogSettings")," namespace).")),(0,i.kt)("h3",{id:"getcontrollerendpoint"},(0,i.kt)("inlineCode",{parentName:"h3"},"getController(endpoint)")),(0,i.kt)("p",null,"Method to get a controller instance to manage trials (start, stop, inquire, etc)."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"endpoint"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - URL of the connection to the Orchestrator.")),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"Controller")," - An instance of the Controller class used to manage trials."),(0,i.kt)("h3",{id:"async-jointrialtrialid-endpoint-actorname"},(0,i.kt)("inlineCode",{parentName:"h3"},"async joinTrial(trialId, endpoint, actorName)")),(0,i.kt)("p",null,"Method for an actor to asynchronously join an existing trial. This task will normally end after the user implementation has exited."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialId"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - The UUID of the trial to join."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"endpoint"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - URL of the connection to the Orchestrator."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"actorName"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - Name of the actor joining the trial.")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h3",{id:"registeractorimpl-actorname-actorclass"},(0,i.kt)("inlineCode",{parentName:"h3"},"registerActor(impl, actorName, actorClass)")),(0,i.kt)("p",null,"Method to register the asynchronous callback function that will run an actor for a trial."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"impl"),": ",(0,i.kt)("em",{parentName:"li"},"async function(ActorSession instance)")," - Callback function to be registered."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"actorName"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - Name for the actor implementation being run by the given callback function."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"actorClass"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - The actor class name that can be run by the given callback function. The possible names are specified in spec file under section ",(0,i.kt)("inlineCode",{parentName:"li"},"actorClasses:name"),". If the list is empty, this implementation can run any actor class.")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h2",{id:"class-controller"},"class Controller"),(0,i.kt)("p",null,"Class containing data and methods to control and manage trials."),(0,i.kt)("h3",{id:"async-starttrialtrialconfig--undefined-trialidrequested--undefined"},(0,i.kt)("inlineCode",{parentName:"h3"},"async startTrial(trialConfig = undefined, trialIdRequested = undefined)")),(0,i.kt)("p",null,"Method to start a new trial. The parameters of the trial will be set by the pre-trial hooks (registered in ",(0,i.kt)("inlineCode",{parentName:"p"},"cogment.Context"),"), and the hooks will receive the provided trial config."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialConfig"),": ",(0,i.kt)("em",{parentName:"li"},"cogment.MessageBase")," - Configuration for the trial. The type is specified in the spec file under the section ",(0,i.kt)("inlineCode",{parentName:"li"},"trial:config_type"),". Can be ",(0,i.kt)("inlineCode",{parentName:"li"},"undefined")," if no configuration is provided. This is provided to the first pre-trial hook."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialIdRequested"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - The trial identifier requested for the new trial. It must be unique among all active trials and a limited set of the latest ended trials (this list of trials can be retrieved with ",(0,i.kt)("inlineCode",{parentName:"li"},"getTrialInfo")," or ",(0,i.kt)("inlineCode",{parentName:"li"},"watchTrial"),"). If provided, the Orchestrator will try to use this trialId, otherwise, a UUID will be created.")),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"string")," - The newly started trial ID."),(0,i.kt)("h3",{id:"terminatetrialtrialids-hard--false"},(0,i.kt)("inlineCode",{parentName:"h3"},"terminateTrial(trialIds, hard = false)")),(0,i.kt)("p",null,"Method to request the end of a trial."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialIds"),": ",(0,i.kt)("em",{parentName:"li"},"string[]")," - The trial ID(s) to request to terminate. There must be at least one ID."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"hard"),": ",(0,i.kt)("em",{parentName:"li"},"boolean")," - If ",(0,i.kt)("inlineCode",{parentName:"li"},"true"),", the termination will be forced and not wait for any action or observation. If ",(0,i.kt)("inlineCode",{parentName:"li"},"false"),", the trial will wait for the next tick, to end gracefully (i.e. wait for the next full set of actions and response observations).")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h3",{id:"async-gettrialinfotrialids"},(0,i.kt)("inlineCode",{parentName:"h3"},"async getTrialInfo(trialIds)")),(0,i.kt)("p",null,"Method to get information about a trial."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialIds"),": ",(0,i.kt)("em",{parentName:"li"},"string[]")," - The trial ID(s) from which to request information. If no ID is provided, returns information about all trials. Note that ended trials may only appear for a short time in this list after they have ended.")),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"TrialInfo[]")," - List of trial information, one per trial. Can be empty if no trial matches."),(0,i.kt)("h3",{id:"async-watchtrialstrialstatefilters"},(0,i.kt)("inlineCode",{parentName:"h3"},"async watchTrials(trialStateFilters=[])")),(0,i.kt)("p",null,"Generator method to iterate, in real-time, through all trial states matching the filters. When called, it will first iterate over the current states matching the filters, for all trials. Afterwards, it will iterate in real-time over the matching states as they change."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialStateFilters"),": ",(0,i.kt)("em",{parentName:"li"},"cogment.TrialState[]")," - List of enum values from ",(0,i.kt)("inlineCode",{parentName:"li"},"cogment.TrialState")," for which we are interested in receiving state changes.")),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"generator(TrialInfo instance)")," - A generator for the state changes that arrive. The ",(0,i.kt)("inlineCode",{parentName:"p"},"TrialInfo")," received here only contains the trial ID and the state."),(0,i.kt)("h3",{id:"async-getactorstrialid"},(0,i.kt)("inlineCode",{parentName:"h3"},"async getActors(trialId)")),(0,i.kt)("p",null,"Method to get the list of configured actors in a trial."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"trialId"),": ",(0,i.kt)("em",{parentName:"li"},"string")," - The trial ID from which to request the list of actors.")),(0,i.kt)("p",null,"Return: ActorInfo[] - List of actors configured in this trial."),(0,i.kt)("h3",{id:"async-getremoteversions"},(0,i.kt)("inlineCode",{parentName:"h3"},"async getRemoteVersions()")),(0,i.kt)("p",null,"Method to get the versions from the remote Orchestrator."),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"{","[key: string]",": string}")," - The key of the object is the name of the component (",(0,i.kt)("em",{parentName:"p"},"string"),"), and the value is the version (",(0,i.kt)("em",{parentName:"p"},"string"),")."),(0,i.kt)("h2",{id:"class-session"},"class Session"),(0,i.kt)("p",null,"Abstract class that manages aspects of a trial. Contains data and methods common to all sessions ."),(0,i.kt)("h3",{id:"gettrialid"},(0,i.kt)("inlineCode",{parentName:"h3"},"getTrialId()")),(0,i.kt)("p",null,"Method to get the UUID of the trial managed by this session."),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"string")," - UUID of the trial."),(0,i.kt)("h3",{id:"gettickid"},(0,i.kt)("inlineCode",{parentName:"h3"},"getTickId()")),(0,i.kt)("p",null,"Method to get the current tick id of the trial (i.e. time step)."),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"number")," - The current tick id."),(0,i.kt)("h3",{id:"istrialover"},(0,i.kt)("inlineCode",{parentName:"h3"},"isTrialOver()")),(0,i.kt)("p",null,"Method to inquire if the current trial has ended."),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"boolean")," - True if the trial has ended, false otherwise."),(0,i.kt)("h3",{id:"sendingdone"},(0,i.kt)("inlineCode",{parentName:"h3"},"sendingDone()")),(0,i.kt)("p",null,"Method to notify the Orchestrator that all data for the trial, from this session, has been sent. This can be called only when the session is ending. When starting the session (see ",(0,i.kt)("inlineCode",{parentName:"p"},"ActorSession"),"), if the ",(0,i.kt)("inlineCode",{parentName:"p"},"autoDoneSending")," parameter is True, this method should not be called, and if the parameter is False, it MUST be called to end the trial properly."),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h2",{id:"class-actorsession-extends-session"},"class ActorSession extends Session"),(0,i.kt)("h3",{id:"startautodonesendingtrue"},(0,i.kt)("inlineCode",{parentName:"h3"},"start(autoDoneSending=True)")),(0,i.kt)("p",null,"Method to start the actor. This method should be called before any other method in the session."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"autoDoneSending"),": ",(0,i.kt)("em",{parentName:"li"},"boolean")," - Controls when to notify the Orchestrator that all data has been sent. If True, the session will automatically send the notification after receiving the last observation. If False, the user MUST call ",(0,i.kt)("inlineCode",{parentName:"li"},"sendingDone")," to end the trial properly.")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h3",{id:"async-eventloop"},(0,i.kt)("inlineCode",{parentName:"h3"},"async *eventLoop()")),(0,i.kt)("p",null,"Generator method to iterate over all events (observations, rewards, messages) as they are received. This will block and wait for an event.\nWhen this generator exits, the callback function (registered with ",(0,i.kt)("inlineCode",{parentName:"p"},"registerActor"),') should return to end the trial cleanly.\nThe generator will exit for various reasons indicating the end of the trial, a loss of communication with the orchestrator, or if the generator is sent "False".'),(0,i.kt)("p",null,"Parameters: None"),(0,i.kt)("p",null,"Return: ",(0,i.kt)("em",{parentName:"p"},"AsyncGenerator")," - A generator for the events that arrive. The ",(0,i.kt)("inlineCode",{parentName:"p"},"RecvEvent")," instances received from this generator will not contain actions. When receiving an observation in the event, the ",(0,i.kt)("inlineCode",{parentName:"p"},"this.doAction"),' method is normally used to "reply" (if the event type is ',(0,i.kt)("inlineCode",{parentName:"p"},"EventType.ACTIVE"),")."),(0,i.kt)("h3",{id:"doactionaction"},(0,i.kt)("inlineCode",{parentName:"h3"},"doAction(action)")),(0,i.kt)("p",null,"Method to send actions to the environment."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"action"),": ",(0,i.kt)("em",{parentName:"li"},"ActionT")," - An instance of the action space class specified in the corresponding section ",(0,i.kt)("inlineCode",{parentName:"li"},"actorClasses:action:space")," of the spec file. If ",(0,i.kt)("inlineCode",{parentName:"li"},"undefined"),", then no action space is sent (empty content) and the environment will receive a default initialized action space of the appropriate type.")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h3",{id:"sendmessagepayload-to"},(0,i.kt)("inlineCode",{parentName:"h3"},"sendMessage(payload, to)")),(0,i.kt)("p",null,"Method to send a message related to the current time step (tick id)."),(0,i.kt)("p",null,"Parameters:"),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"payload"),": ",(0,i.kt)("em",{parentName:"li"},"cogment.MessageBase")," - The message data to be sent. The class can be any protobuf class. It is the responsibility of the receiving actor to manage the class received."),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("inlineCode",{parentName:"li"},"to"),": ",(0,i.kt)("em",{parentName:"li"},"string[]")," - Targets of feedback. Each value could be the name of an actor in the trial, or the name of the environment (from ",(0,i.kt)("inlineCode",{parentName:"li"},"this.envName"),'). Or it could represent a set of actors (with wildcards); A set of actors can be represented with the wildcard character "',(0,i.kt)("inlineCode",{parentName:"li"},"*"),'" for all actors (of all classes), or "',(0,i.kt)("inlineCode",{parentName:"li"},"actorClass.*"),'" for all actors of a specific class (the ',(0,i.kt)("inlineCode",{parentName:"li"},"actorClass")," must match one of the classes listed in the trial parameters). Note that the wildcard does not include the environment.")),(0,i.kt)("p",null,"Return: void"),(0,i.kt)("h2",{id:"enum-cogmenttrialstate"},"enum cogment.TrialState"),(0,i.kt)("p",null,"Enum representing the various states of trials."),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},"UNKNOWN: Should not be used."),(0,i.kt)("li",{parentName:"ul"},"INITIALIZING: The trial is in the process of starting."),(0,i.kt)("li",{parentName:"ul"},"PENDING: The trial is waiting for its final parameters, before running."),(0,i.kt)("li",{parentName:"ul"},"RUNNING: The trial is running."),(0,i.kt)("li",{parentName:"ul"},"TERMINATING: The trial is in the process of terminating (either a request to terminate has been received or the last observation has been received)."),(0,i.kt)("li",{parentName:"ul"},"ENDED: The trial has ended. Only a set number of ended trials will be kept (configured in the Orchestrator).")),(0,i.kt)("p",null,"For further information on trial lifetime, check the ",(0,i.kt)("a",{parentName:"p",href:"/docs/guide/development-guide#trial-lifetime"},"dedicated section"),"."),(0,i.kt)("h2",{id:"class-trialinfo"},"class TrialInfo"),(0,i.kt)("p",null,"Class enclosing the details of a trial."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"trialId"),": ",(0,i.kt)("em",{parentName:"p"},"string")," - The trial ID to which the details pertain."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"state"),": ",(0,i.kt)("em",{parentName:"p"},"cogment.TrialState")," - The current state of the trial."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"envName"),": ",(0,i.kt)("em",{parentName:"p"},"string")," - The name of the environment running the trial."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"tickId"),": ",(0,i.kt)("em",{parentName:"p"},"number")," - The time step that the information relates to. Only provided from a call to ",(0,i.kt)("inlineCode",{parentName:"p"},"getTrialInfo"),"."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"duration"),": ",(0,i.kt)("em",{parentName:"p"},"number")," - The time (in nanoseconds) that the trial has run. Only provided from a call to ",(0,i.kt)("inlineCode",{parentName:"p"},"getTrialInfo"),"."),(0,i.kt)("h2",{id:"class-recvevent"},"class RecvEvent"),(0,i.kt)("p",null,"Class representing a received event (for environments and actors). It can contain any combination of data according to the receiver needs, or even be empty, but it will always have a type."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"type"),": ",(0,i.kt)("em",{parentName:"p"},"EventType")," - Type of event the enclosed data represents."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"observation"),": ",(0,i.kt)("em",{parentName:"p"},"ObservationT")," - Observation data. This can only be received by actors. ",(0,i.kt)("inlineCode",{parentName:"p"},"undefined")," if not present."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"actions"),": ",(0,i.kt)("em",{parentName:"p"},"ActionT")," - Action data from actors. This can only be received by the environment. The list is empty if not present."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"rewards"),": ",(0,i.kt)("em",{parentName:"p"},"Reward[]")," - Reward values and data. This can only be received by actors. The list is empty if not present."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"messages"),": ",(0,i.kt)("em",{parentName:"p"},"MessageBase[]")," - Message data. The list is empty if not present."),(0,i.kt)("h3",{id:"enum-cogmenteventtype"},"enum cogment.EventType"),(0,i.kt)("p",null,"Enum representing the type of an event."),(0,i.kt)("ul",null,(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("inlineCode",{parentName:"p"},"EventType.NONE"),": Empty event. This kind of event should never be received.")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("inlineCode",{parentName:"p"},"EventType.ACTIVE"),": Normal event from an active trial. Most events will be of this type.")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("inlineCode",{parentName:"p"},"EventType.ENDING"),": Events from a trial in the process of ending. For the environment, this means that these events contain the last actions from the actors, and the trial is awaiting a final observation. For the actors, this means that the trial is ending and no action can/need to be sent in response. Note that because of network timing, there may be ",(0,i.kt)("inlineCode",{parentName:"p"},"ACTIVE")," events (e.g. rewards or messages) arriving after some ",(0,i.kt)("inlineCode",{parentName:"p"},"ENDING")," events, but the trial is ending regardless.")),(0,i.kt)("li",{parentName:"ul"},(0,i.kt)("p",{parentName:"li"},(0,i.kt)("inlineCode",{parentName:"p"},"EventType.FINAL"),": Final event for the trial. This does not contain data. The event loop will exit after this event is delivered. This event can be ignored if nothing needs to be done before exiting the loop."))),(0,i.kt)("p",null,"For further information on trial lifetime, check the ",(0,i.kt)("a",{parentName:"p",href:"/docs/guide/development-guide#trial-lifetime"},"dedicated section"),"."),(0,i.kt)("h2",{id:"type-observationt"},"type ObservationT"),(0,i.kt)("p",null,"Type containing the details of an actor's observation. This will be different depending on what the ActionSpace defined in your spec file contains"),(0,i.kt)("h2",{id:"type-actiont"},"type ActionT"),(0,i.kt)("p",null,"Type containing the details of an action from an actor. This will be different depending on what the ActionSpace defined in your spec file contains"),(0,i.kt)("h2",{id:"class-messagebase"},"class MessageBase"),(0,i.kt)("p",null,"Base Class of all messages, this will contain different fields depending on what fields are in the specific message you are receiving (defined in proto files)"),(0,i.kt)("h2",{id:"type-reward"},"type Reward"),(0,i.kt)("p",null,"type containing the details of a received reward."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"tickId"),": ",(0,i.kt)("em",{parentName:"p"},"number")," - The tick id (time step) for which the reward should be applied."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"receiverName"),": ",(0,i.kt)("em",{parentName:"p"},"string")," - Name of the receiver for the reward (the name of an actor, or wildcard string)."),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"value"),": ",(0,i.kt)("em",{parentName:"p"},"float")," - Value of the reward (aggregated from the sources)"),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"sources"),": ",(0,i.kt)("em",{parentName:"p"},"IRewardSource[]")," - List of sources that gave this reward"),(0,i.kt)("h2",{id:"interface-irewardsource"},"interface IRewardSource"),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"senderName"),": ",(0,i.kt)("em",{parentName:"p"},"string")," - Name of the reward sender;"),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"value"),": ",(0,i.kt)("em",{parentName:"p"},"number")," - Value of the reward;"),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"confidence"),": ",(0,i.kt)("em",{parentName:"p"},"number")," - Confidence of this reward;"),(0,i.kt)("p",null,(0,i.kt)("inlineCode",{parentName:"p"},"userData"),": ",(0,i.kt)("em",{parentName:"p"},"google.protobuf.IAny")," - Extra data;"))}c.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/ac5280f2.23c0bab4.js b/assets/js/ac5280f2.23c0bab4.js new file mode 100644 index 0000000..6432e44 --- /dev/null +++ b/assets/js/ac5280f2.23c0bab4.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkcogment_doc=self.webpackChunkcogment_doc||[]).push([[8529],{3905:(e,t,n)=>{n.d(t,{Zo:()=>d,kt:()=>p});var i=n(7294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);t&&(i=i.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,i)}return n}function a(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(i=0;i=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=i.createContext({}),c=function(e){var t=i.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},d=function(e){var t=c(e.components);return i.createElement(l.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return i.createElement(i.Fragment,{},t)}},h=i.forwardRef((function(e,t){var n=e.components,o=e.mdxType,r=e.originalType,l=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),h=c(n),p=o,f=h["".concat(l,".").concat(p)]||h[p]||u[p]||r;return n?i.createElement(f,a(a({ref:t},d),{},{components:n})):i.createElement(f,a({ref:t},d))}));function p(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var r=n.length,a=new Array(r);a[0]=h;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:o,a[1]=s;for(var c=2;c{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>a,default:()=>u,frontMatter:()=>r,metadata:()=>s,toc:()=>c});var i=n(7462),o=(n(7294),n(3905));const r={sidebar_position:7},a="Apache License",s={unversionedId:"license",id:"license",title:"Apache License",description:"Version 2.0, January 2004",source:"@site/docs/license.md",sourceDirName:".",slug:"/license",permalink:"/docs/license",draft:!1,tags:[],version:"current",lastUpdatedAt:1665585711,formattedLastUpdatedAt:"Oct 12, 2022",sidebarPosition:7,frontMatter:{sidebar_position:7},sidebar:"docSidebar",previous:{title:"Cogment 2.0",permalink:"/docs/reference/cogment-v2-changes"}},l={},c=[{value:"Terms and Conditions for use, reproduction, and distribution",id:"terms-and-conditions-for-use-reproduction-and-distribution",level:3},{value:"1. Definitions",id:"1-definitions",level:4},{value:"2. Grant of Copyright License",id:"2-grant-of-copyright-license",level:4},{value:"3. Grant of Patent License",id:"3-grant-of-patent-license",level:4},{value:"4. Redistribution",id:"4-redistribution",level:4},{value:"5. Submission of Contributions",id:"5-submission-of-contributions",level:4},{value:"6. Trademarks",id:"6-trademarks",level:4},{value:"7. Disclaimer of Warranty",id:"7-disclaimer-of-warranty",level:4},{value:"8. Limitation of Liability",id:"8-limitation-of-liability",level:4},{value:"9. Accepting Warranty or Additional Liability",id:"9-accepting-warranty-or-additional-liability",level:4}],d={toc:c};function u(e){let{components:t,...n}=e;return(0,o.kt)("wrapper",(0,i.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"apache-license"},"Apache License"),(0,o.kt)("p",null,(0,o.kt)("em",{parentName:"p"},"Version 2.0, January 2004"),"\n",(0,o.kt)("em",{parentName:"p"},"<",(0,o.kt)("a",{parentName:"em",href:"http://www.apache.org/licenses/"},"http://www.apache.org/licenses/"),">")),(0,o.kt)("h3",{id:"terms-and-conditions-for-use-reproduction-and-distribution"},"Terms and Conditions for use, reproduction, and distribution"),(0,o.kt)("h4",{id:"1-definitions"},"1. Definitions"),(0,o.kt)("p",null,"\u201cLicense\u201d shall mean the terms and conditions for use, reproduction, and\ndistribution as defined by Sections 1 through 9 of this document."),(0,o.kt)("p",null,"\u201cLicensor\u201d shall mean the copyright owner or entity authorized by the copyright\nowner that is granting the License."),(0,o.kt)("p",null,"\u201cLegal Entity\u201d shall mean the union of the acting entity and all other entities\nthat control, are controlled by, or are under common control with that entity.\nFor the purposes of this definition, \u201ccontrol\u201d means ",(0,o.kt)("strong",{parentName:"p"},"(i)")," the power, direct or\nindirect, to cause the direction or management of such entity, whether by\ncontract or otherwise, or ",(0,o.kt)("strong",{parentName:"p"},"(ii)")," ownership of fifty percent (50%) or more of the\noutstanding shares, or ",(0,o.kt)("strong",{parentName:"p"},"(iii)")," beneficial ownership of such entity."),(0,o.kt)("p",null,"\u201cYou\u201d (or \u201cYour\u201d) shall mean an individual or Legal Entity exercising\npermissions granted by this License."),(0,o.kt)("p",null,"\u201cSource\u201d form shall mean the preferred form for making modifications, including\nbut not limited to software source code, documentation source, and configuration\nfiles."),(0,o.kt)("p",null,"\u201cObject\u201d form shall mean any form resulting from mechanical transformation or\ntranslation of a Source form, including but not limited to compiled object code,\ngenerated documentation, and conversions to other media types."),(0,o.kt)("p",null,"\u201cWork\u201d shall mean the work of authorship, whether in Source or Object form, made\navailable under the License, as indicated by a copyright notice that is included\nin or attached to the work (an example is provided in the Appendix below)."),(0,o.kt)("p",null,"\u201cDerivative Works\u201d shall mean any work, whether in Source or Object form, that\nis based on (or derived from) the Work and for which the editorial revisions,\nannotations, elaborations, or other modifications represent, as a whole, an\noriginal work of authorship. For the purposes of this License, Derivative Works\nshall not include works that remain separable from, or merely link (or bind by\nname) to the interfaces of, the Work and Derivative Works thereof."),(0,o.kt)("p",null,"\u201cContribution\u201d shall mean any work of authorship, including the original version\nof the Work and any modifications or additions to that Work or Derivative Works\nthereof, that is intentionally submitted to Licensor for inclusion in the Work\nby the copyright owner or by an individual or Legal Entity authorized to submit\non behalf of the copyright owner. For the purposes of this definition,\n\u201csubmitted\u201d means any form of electronic, verbal, or written communication sent\nto the Licensor or its representatives, including but not limited to\ncommunication on electronic mailing lists, source code control systems, and\nissue tracking systems that are managed by, or on behalf of, the Licensor for\nthe purpose of discussing and improving the Work, but excluding communication\nthat is conspicuously marked or otherwise designated in writing by the copyright\nowner as \u201cNot a Contribution.\u201d"),(0,o.kt)("p",null,"\u201cContributor\u201d shall mean Licensor and any individual or Legal Entity on behalf\nof whom a Contribution has been received by Licensor and subsequently\nincorporated within the Work."),(0,o.kt)("h4",{id:"2-grant-of-copyright-license"},"2. Grant of Copyright License"),(0,o.kt)("p",null,"Subject to the terms and conditions of this License, each Contributor hereby\ngrants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,\nirrevocable copyright license to reproduce, prepare Derivative Works of,\npublicly display, publicly perform, sublicense, and distribute the Work and such\nDerivative Works in Source or Object form."),(0,o.kt)("h4",{id:"3-grant-of-patent-license"},"3. Grant of Patent License"),(0,o.kt)("p",null,"Subject to the terms and conditions of this License, each Contributor hereby\ngrants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,\nirrevocable (except as stated in this section) patent license to make, have\nmade, use, offer to sell, sell, import, and otherwise transfer the Work, where\nsuch license applies only to those patent claims licensable by such Contributor\nthat are necessarily infringed by their Contribution(s) alone or by combination\nof their Contribution(s) with the Work to which such Contribution(s) was\nsubmitted. If You institute patent litigation against any entity (including a\ncross-claim or counterclaim in a lawsuit) alleging that the Work or a\nContribution incorporated within the Work constitutes direct or contributory\npatent infringement, then any patent licenses granted to You under this License\nfor that Work shall terminate as of the date such litigation is filed."),(0,o.kt)("h4",{id:"4-redistribution"},"4. Redistribution"),(0,o.kt)("p",null,"You may reproduce and distribute copies of the Work or Derivative Works thereof\nin any medium, with or without modifications, and in Source or Object form,\nprovided that You meet the following conditions:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"(a)")," You must give any other recipients of the Work or Derivative Works a copy of\nthis License; and"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"(b)")," You must cause any modified files to carry prominent notices stating that You\nchanged the files; and"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"(c)")," You must retain, in the Source form of any Derivative Works that You distribute,\nall copyright, patent, trademark, and attribution notices from the Source form\nof the Work, excluding those notices that do not pertain to any part of the\nDerivative Works; and"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"(d)")," If the Work includes a \u201cNOTICE\u201d text file as part of its distribution, then any\nDerivative Works that You distribute must include a readable copy of the\nattribution notices contained within such NOTICE file, excluding those notices\nthat do not pertain to any part of the Derivative Works, in at least one of the\nfollowing places: within a NOTICE text file distributed as part of the\nDerivative Works; within the Source form or documentation, if provided along\nwith the Derivative Works; or, within a display generated by the Derivative\nWorks, if and wherever such third-party notices normally appear. The contents of\nthe NOTICE file are for informational purposes only and do not modify the\nLicense. You may add Your own attribution notices within Derivative Works that\nYou distribute, alongside or as an addendum to the NOTICE text from the Work,\nprovided that such additional attribution notices cannot be construed as\nmodifying the License.")),(0,o.kt)("p",null,"You may add Your own copyright statement to Your modifications and may provide\nadditional or different license terms and conditions for use, reproduction, or\ndistribution of Your modifications, or for any such Derivative Works as a whole,\nprovided Your use, reproduction, and distribution of the Work otherwise complies\nwith the conditions stated in this License."),(0,o.kt)("h4",{id:"5-submission-of-contributions"},"5. Submission of Contributions"),(0,o.kt)("p",null,"Unless You explicitly state otherwise, any Contribution intentionally submitted\nfor inclusion in the Work by You to the Licensor shall be under the terms and\nconditions of this License, without any additional terms or conditions.\nNotwithstanding the above, nothing herein shall supersede or modify the terms of\nany separate license agreement you may have executed with Licensor regarding\nsuch Contributions."),(0,o.kt)("h4",{id:"6-trademarks"},"6. Trademarks"),(0,o.kt)("p",null,"This License does not grant permission to use the trade names, trademarks,\nservice marks, or product names of the Licensor, except as required for\nreasonable and customary use in describing the origin of the Work and\nreproducing the content of the NOTICE file."),(0,o.kt)("h4",{id:"7-disclaimer-of-warranty"},"7. Disclaimer of Warranty"),(0,o.kt)("p",null,"Unless required by applicable law or agreed to in writing, Licensor provides the\nWork (and each Contributor provides its Contributions) on an \u201cAS IS\u201d BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,\nincluding, without limitation, any warranties or conditions of TITLE,\nNON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are\nsolely responsible for determining the appropriateness of using or\nredistributing the Work and assume any risks associated with Your exercise of\npermissions under this License."),(0,o.kt)("h4",{id:"8-limitation-of-liability"},"8. Limitation of Liability"),(0,o.kt)("p",null,"In no event and under no legal theory, whether in tort (including negligence),\ncontract, or otherwise, unless required by applicable law (such as deliberate\nand grossly negligent acts) or agreed to in writing, shall any Contributor be\nliable to You for damages, including any direct, indirect, special, incidental,\nor consequential damages of any character arising as a result of this License or\nout of the use or inability to use the Work (including but not limited to\ndamages for loss of goodwill, work stoppage, computer failure or malfunction, or\nany and all other commercial damages or losses), even if such Contributor has\nbeen advised of the possibility of such damages."),(0,o.kt)("h4",{id:"9-accepting-warranty-or-additional-liability"},"9. Accepting Warranty or Additional Liability"),(0,o.kt)("p",null,"While redistributing the Work or Derivative Works thereof, You may choose to\noffer, and charge a fee for, acceptance of support, warranty, indemnity, or\nother liability obligations and/or rights consistent with this License. However,\nin accepting such obligations, You may act only on Your own behalf and on Your\nsole responsibility, not on behalf of any other Contributor, and only if You\nagree to indemnify, defend, and hold each Contributor harmless for any liability\nincurred by, or claims asserted against, such Contributor by reason of your\naccepting any such warranty or additional liability."),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"Copyright 2019 Artificial Intelligence Redefined")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/ac5280f2.476e8c59.js b/assets/js/ac5280f2.476e8c59.js deleted file mode 100644 index 95acc87..0000000 --- a/assets/js/ac5280f2.476e8c59.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkcogment_doc=self.webpackChunkcogment_doc||[]).push([[8529],{3905:(e,t,n)=>{n.d(t,{Zo:()=>d,kt:()=>p});var i=n(7294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);t&&(i=i.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,i)}return n}function a(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(i=0;i=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=i.createContext({}),c=function(e){var t=i.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},d=function(e){var t=c(e.components);return i.createElement(l.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return i.createElement(i.Fragment,{},t)}},h=i.forwardRef((function(e,t){var n=e.components,o=e.mdxType,r=e.originalType,l=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),h=c(n),p=o,f=h["".concat(l,".").concat(p)]||h[p]||u[p]||r;return n?i.createElement(f,a(a({ref:t},d),{},{components:n})):i.createElement(f,a({ref:t},d))}));function p(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var r=n.length,a=new Array(r);a[0]=h;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:o,a[1]=s;for(var c=2;c{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>a,default:()=>u,frontMatter:()=>r,metadata:()=>s,toc:()=>c});var i=n(7462),o=(n(7294),n(3905));const r={sidebar_position:7},a="Apache License",s={unversionedId:"license",id:"license",title:"Apache License",description:"Version 2.0, January 2004",source:"@site/docs/license.md",sourceDirName:".",slug:"/license",permalink:"/docs/license",draft:!1,tags:[],version:"current",lastUpdatedAt:1664807199,formattedLastUpdatedAt:"Oct 3, 2022",sidebarPosition:7,frontMatter:{sidebar_position:7},sidebar:"docSidebar",previous:{title:"Cogment 2.0",permalink:"/docs/reference/cogment-v2-changes"}},l={},c=[{value:"Terms and Conditions for use, reproduction, and distribution",id:"terms-and-conditions-for-use-reproduction-and-distribution",level:3},{value:"1. Definitions",id:"1-definitions",level:4},{value:"2. Grant of Copyright License",id:"2-grant-of-copyright-license",level:4},{value:"3. Grant of Patent License",id:"3-grant-of-patent-license",level:4},{value:"4. Redistribution",id:"4-redistribution",level:4},{value:"5. Submission of Contributions",id:"5-submission-of-contributions",level:4},{value:"6. Trademarks",id:"6-trademarks",level:4},{value:"7. Disclaimer of Warranty",id:"7-disclaimer-of-warranty",level:4},{value:"8. Limitation of Liability",id:"8-limitation-of-liability",level:4},{value:"9. Accepting Warranty or Additional Liability",id:"9-accepting-warranty-or-additional-liability",level:4}],d={toc:c};function u(e){let{components:t,...n}=e;return(0,o.kt)("wrapper",(0,i.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h1",{id:"apache-license"},"Apache License"),(0,o.kt)("p",null,(0,o.kt)("em",{parentName:"p"},"Version 2.0, January 2004"),"\n",(0,o.kt)("em",{parentName:"p"},"<",(0,o.kt)("a",{parentName:"em",href:"http://www.apache.org/licenses/"},"http://www.apache.org/licenses/"),">")),(0,o.kt)("h3",{id:"terms-and-conditions-for-use-reproduction-and-distribution"},"Terms and Conditions for use, reproduction, and distribution"),(0,o.kt)("h4",{id:"1-definitions"},"1. Definitions"),(0,o.kt)("p",null,"\u201cLicense\u201d shall mean the terms and conditions for use, reproduction, and\ndistribution as defined by Sections 1 through 9 of this document."),(0,o.kt)("p",null,"\u201cLicensor\u201d shall mean the copyright owner or entity authorized by the copyright\nowner that is granting the License."),(0,o.kt)("p",null,"\u201cLegal Entity\u201d shall mean the union of the acting entity and all other entities\nthat control, are controlled by, or are under common control with that entity.\nFor the purposes of this definition, \u201ccontrol\u201d means ",(0,o.kt)("strong",{parentName:"p"},"(i)")," the power, direct or\nindirect, to cause the direction or management of such entity, whether by\ncontract or otherwise, or ",(0,o.kt)("strong",{parentName:"p"},"(ii)")," ownership of fifty percent (50%) or more of the\noutstanding shares, or ",(0,o.kt)("strong",{parentName:"p"},"(iii)")," beneficial ownership of such entity."),(0,o.kt)("p",null,"\u201cYou\u201d (or \u201cYour\u201d) shall mean an individual or Legal Entity exercising\npermissions granted by this License."),(0,o.kt)("p",null,"\u201cSource\u201d form shall mean the preferred form for making modifications, including\nbut not limited to software source code, documentation source, and configuration\nfiles."),(0,o.kt)("p",null,"\u201cObject\u201d form shall mean any form resulting from mechanical transformation or\ntranslation of a Source form, including but not limited to compiled object code,\ngenerated documentation, and conversions to other media types."),(0,o.kt)("p",null,"\u201cWork\u201d shall mean the work of authorship, whether in Source or Object form, made\navailable under the License, as indicated by a copyright notice that is included\nin or attached to the work (an example is provided in the Appendix below)."),(0,o.kt)("p",null,"\u201cDerivative Works\u201d shall mean any work, whether in Source or Object form, that\nis based on (or derived from) the Work and for which the editorial revisions,\nannotations, elaborations, or other modifications represent, as a whole, an\noriginal work of authorship. For the purposes of this License, Derivative Works\nshall not include works that remain separable from, or merely link (or bind by\nname) to the interfaces of, the Work and Derivative Works thereof."),(0,o.kt)("p",null,"\u201cContribution\u201d shall mean any work of authorship, including the original version\nof the Work and any modifications or additions to that Work or Derivative Works\nthereof, that is intentionally submitted to Licensor for inclusion in the Work\nby the copyright owner or by an individual or Legal Entity authorized to submit\non behalf of the copyright owner. For the purposes of this definition,\n\u201csubmitted\u201d means any form of electronic, verbal, or written communication sent\nto the Licensor or its representatives, including but not limited to\ncommunication on electronic mailing lists, source code control systems, and\nissue tracking systems that are managed by, or on behalf of, the Licensor for\nthe purpose of discussing and improving the Work, but excluding communication\nthat is conspicuously marked or otherwise designated in writing by the copyright\nowner as \u201cNot a Contribution.\u201d"),(0,o.kt)("p",null,"\u201cContributor\u201d shall mean Licensor and any individual or Legal Entity on behalf\nof whom a Contribution has been received by Licensor and subsequently\nincorporated within the Work."),(0,o.kt)("h4",{id:"2-grant-of-copyright-license"},"2. Grant of Copyright License"),(0,o.kt)("p",null,"Subject to the terms and conditions of this License, each Contributor hereby\ngrants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,\nirrevocable copyright license to reproduce, prepare Derivative Works of,\npublicly display, publicly perform, sublicense, and distribute the Work and such\nDerivative Works in Source or Object form."),(0,o.kt)("h4",{id:"3-grant-of-patent-license"},"3. Grant of Patent License"),(0,o.kt)("p",null,"Subject to the terms and conditions of this License, each Contributor hereby\ngrants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,\nirrevocable (except as stated in this section) patent license to make, have\nmade, use, offer to sell, sell, import, and otherwise transfer the Work, where\nsuch license applies only to those patent claims licensable by such Contributor\nthat are necessarily infringed by their Contribution(s) alone or by combination\nof their Contribution(s) with the Work to which such Contribution(s) was\nsubmitted. If You institute patent litigation against any entity (including a\ncross-claim or counterclaim in a lawsuit) alleging that the Work or a\nContribution incorporated within the Work constitutes direct or contributory\npatent infringement, then any patent licenses granted to You under this License\nfor that Work shall terminate as of the date such litigation is filed."),(0,o.kt)("h4",{id:"4-redistribution"},"4. Redistribution"),(0,o.kt)("p",null,"You may reproduce and distribute copies of the Work or Derivative Works thereof\nin any medium, with or without modifications, and in Source or Object form,\nprovided that You meet the following conditions:"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"(a)")," You must give any other recipients of the Work or Derivative Works a copy of\nthis License; and"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"(b)")," You must cause any modified files to carry prominent notices stating that You\nchanged the files; and"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"(c)")," You must retain, in the Source form of any Derivative Works that You distribute,\nall copyright, patent, trademark, and attribution notices from the Source form\nof the Work, excluding those notices that do not pertain to any part of the\nDerivative Works; and"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("strong",{parentName:"li"},"(d)")," If the Work includes a \u201cNOTICE\u201d text file as part of its distribution, then any\nDerivative Works that You distribute must include a readable copy of the\nattribution notices contained within such NOTICE file, excluding those notices\nthat do not pertain to any part of the Derivative Works, in at least one of the\nfollowing places: within a NOTICE text file distributed as part of the\nDerivative Works; within the Source form or documentation, if provided along\nwith the Derivative Works; or, within a display generated by the Derivative\nWorks, if and wherever such third-party notices normally appear. The contents of\nthe NOTICE file are for informational purposes only and do not modify the\nLicense. You may add Your own attribution notices within Derivative Works that\nYou distribute, alongside or as an addendum to the NOTICE text from the Work,\nprovided that such additional attribution notices cannot be construed as\nmodifying the License.")),(0,o.kt)("p",null,"You may add Your own copyright statement to Your modifications and may provide\nadditional or different license terms and conditions for use, reproduction, or\ndistribution of Your modifications, or for any such Derivative Works as a whole,\nprovided Your use, reproduction, and distribution of the Work otherwise complies\nwith the conditions stated in this License."),(0,o.kt)("h4",{id:"5-submission-of-contributions"},"5. Submission of Contributions"),(0,o.kt)("p",null,"Unless You explicitly state otherwise, any Contribution intentionally submitted\nfor inclusion in the Work by You to the Licensor shall be under the terms and\nconditions of this License, without any additional terms or conditions.\nNotwithstanding the above, nothing herein shall supersede or modify the terms of\nany separate license agreement you may have executed with Licensor regarding\nsuch Contributions."),(0,o.kt)("h4",{id:"6-trademarks"},"6. Trademarks"),(0,o.kt)("p",null,"This License does not grant permission to use the trade names, trademarks,\nservice marks, or product names of the Licensor, except as required for\nreasonable and customary use in describing the origin of the Work and\nreproducing the content of the NOTICE file."),(0,o.kt)("h4",{id:"7-disclaimer-of-warranty"},"7. Disclaimer of Warranty"),(0,o.kt)("p",null,"Unless required by applicable law or agreed to in writing, Licensor provides the\nWork (and each Contributor provides its Contributions) on an \u201cAS IS\u201d BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,\nincluding, without limitation, any warranties or conditions of TITLE,\nNON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are\nsolely responsible for determining the appropriateness of using or\nredistributing the Work and assume any risks associated with Your exercise of\npermissions under this License."),(0,o.kt)("h4",{id:"8-limitation-of-liability"},"8. Limitation of Liability"),(0,o.kt)("p",null,"In no event and under no legal theory, whether in tort (including negligence),\ncontract, or otherwise, unless required by applicable law (such as deliberate\nand grossly negligent acts) or agreed to in writing, shall any Contributor be\nliable to You for damages, including any direct, indirect, special, incidental,\nor consequential damages of any character arising as a result of this License or\nout of the use or inability to use the Work (including but not limited to\ndamages for loss of goodwill, work stoppage, computer failure or malfunction, or\nany and all other commercial damages or losses), even if such Contributor has\nbeen advised of the possibility of such damages."),(0,o.kt)("h4",{id:"9-accepting-warranty-or-additional-liability"},"9. Accepting Warranty or Additional Liability"),(0,o.kt)("p",null,"While redistributing the Work or Derivative Works thereof, You may choose to\noffer, and charge a fee for, acceptance of support, warranty, indemnity, or\nother liability obligations and/or rights consistent with this License. However,\nin accepting such obligations, You may act only on Your own behalf and on Your\nsole responsibility, not on behalf of any other Contributor, and only if You\nagree to indemnify, defend, and hold each Contributor harmless for any liability\nincurred by, or claims asserted against, such Contributor by reason of your\naccepting any such warranty or additional liability."),(0,o.kt)("p",null,(0,o.kt)("strong",{parentName:"p"},"Copyright 2019 Artificial Intelligence Redefined")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/runtime~main.01110f9e.js b/assets/js/runtime~main.08a7e066.js similarity index 54% rename from assets/js/runtime~main.01110f9e.js rename to assets/js/runtime~main.08a7e066.js index cdcee5b..01f8784 100644 --- a/assets/js/runtime~main.01110f9e.js +++ b/assets/js/runtime~main.08a7e066.js @@ -1 +1 @@ -(()=>{"use strict";var e,t,f,r,a,d={},c={};function o(e){var t=c[e];if(void 0!==t)return t.exports;var f=c[e]={id:e,loaded:!1,exports:{}};return d[e].call(f.exports,f,f.exports,o),f.loaded=!0,f.exports}o.m=d,o.c=c,e=[],o.O=(t,f,r,a)=>{if(!f){var d=1/0;for(i=0;i=a)&&Object.keys(o.O).every((e=>o.O[e](f[b])))?f.splice(b--,1):(c=!1,a0&&e[i-1][2]>a;i--)e[i]=e[i-1];e[i]=[f,r,a]},o.n=e=>{var t=e&&e.__esModule?()=>e.default:()=>e;return o.d(t,{a:t}),t},f=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,o.t=function(e,r){if(1&r&&(e=this(e)),8&r)return e;if("object"==typeof e&&e){if(4&r&&e.__esModule)return e;if(16&r&&"function"==typeof e.then)return e}var a=Object.create(null);o.r(a);var d={};t=t||[null,f({}),f([]),f(f)];for(var c=2&r&&e;"object"==typeof c&&!~t.indexOf(c);c=f(c))Object.getOwnPropertyNames(c).forEach((t=>d[t]=()=>e[t]));return d.default=()=>e,o.d(a,d),a},o.d=(e,t)=>{for(var f in t)o.o(t,f)&&!o.o(e,f)&&Object.defineProperty(e,f,{enumerable:!0,get:t[f]})},o.f={},o.e=e=>Promise.all(Object.keys(o.f).reduce(((t,f)=>(o.f[f](e,t),t)),[])),o.u=e=>"assets/js/"+({53:"935f2afb",916:"a57d321a",928:"696a412b",931:"14f1d27f",966:"6c6cf206",1028:"80b5be58",1043:"c3c15305",1257:"76d0d1d8",1455:"d03751be",1909:"b2327a6c",2147:"1b039142",2229:"f012f959",2880:"9b824c8f",3106:"fd5e6f38",3922:"08714d8c",3953:"7a87d372",4007:"d9378b29",4195:"c4f5d8e4",4896:"85f318fb",5089:"8f68e2ce",5171:"61fcde8c",5307:"6f2832ad",5505:"92a77eef",5519:"c24ec994",5649:"c0fe6564",5767:"1d042041",5893:"d04964af",6971:"c377a04b",7107:"be6d912d",7221:"710eddd2",7330:"8f51b104",7918:"17896441",7920:"1a4e3797",8172:"e848be99",8403:"25848ff4",8529:"ac5280f2",8687:"50751b0a",8769:"2d986b69",9071:"354f5e12",9255:"9b35c4f5",9514:"1be78505",9690:"3f8274eb",9921:"4f085710",9985:"8ba33b25"}[e]||e)+"."+{53:"eaa09a8c",916:"7b1da2dc",928:"30d5fb90",931:"e67f3f33",966:"4874a857",1028:"7a80df6d",1043:"0d717cd1",1257:"fef871bb",1455:"3d85882f",1909:"2d13b65b",2147:"34999ad0",2229:"ad12eb4f",2880:"1c11dbd9",3106:"65b6ada4",3922:"8066bd98",3953:"7e5409a8",4007:"6db302b8",4195:"75997564",4698:"8c4037a9",4896:"18658faf",4972:"9c4c5fed",5089:"68e819b0",5171:"4dd88737",5307:"e5b5393c",5505:"3834a1d4",5519:"1b981edd",5649:"fc79d8f6",5767:"3353ac3b",5893:"dad4b03c",6780:"2e464230",6945:"46b11133",6971:"dee11c26",7107:"6d137fe3",7221:"97c3fcd9",7330:"3158977f",7918:"e1ad11d7",7920:"2adc3808",8172:"fe19ea8a",8403:"57f5c5cf",8529:"476e8c59",8687:"2a9afa79",8769:"356337e0",8894:"2f96187b",9071:"28413fb0",9255:"4724485f",9514:"b5adb11b",9690:"7b2c5f8f",9921:"99943333",9985:"993fc35e"}[e]+".js",o.miniCssF=e=>{},o.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),o.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t),r={},a="cogment-doc:",o.l=(e,t,f,d)=>{if(r[e])r[e].push(t);else{var c,b;if(void 0!==f)for(var n=document.getElementsByTagName("script"),i=0;i{c.onerror=c.onload=null,clearTimeout(s);var a=r[e];if(delete r[e],c.parentNode&&c.parentNode.removeChild(c),a&&a.forEach((e=>e(f))),t)return t(f)},s=setTimeout(l.bind(null,void 0,{type:"timeout",target:c}),12e4);c.onerror=l.bind(null,c.onerror),c.onload=l.bind(null,c.onload),b&&document.head.appendChild(c)}},o.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},o.p="/",o.gca=function(e){return e={17896441:"7918","935f2afb":"53",a57d321a:"916","696a412b":"928","14f1d27f":"931","6c6cf206":"966","80b5be58":"1028",c3c15305:"1043","76d0d1d8":"1257",d03751be:"1455",b2327a6c:"1909","1b039142":"2147",f012f959:"2229","9b824c8f":"2880",fd5e6f38:"3106","08714d8c":"3922","7a87d372":"3953",d9378b29:"4007",c4f5d8e4:"4195","85f318fb":"4896","8f68e2ce":"5089","61fcde8c":"5171","6f2832ad":"5307","92a77eef":"5505",c24ec994:"5519",c0fe6564:"5649","1d042041":"5767",d04964af:"5893",c377a04b:"6971",be6d912d:"7107","710eddd2":"7221","8f51b104":"7330","1a4e3797":"7920",e848be99:"8172","25848ff4":"8403",ac5280f2:"8529","50751b0a":"8687","2d986b69":"8769","354f5e12":"9071","9b35c4f5":"9255","1be78505":"9514","3f8274eb":"9690","4f085710":"9921","8ba33b25":"9985"}[e]||e,o.p+o.u(e)},(()=>{var e={1303:0,532:0};o.f.j=(t,f)=>{var r=o.o(e,t)?e[t]:void 0;if(0!==r)if(r)f.push(r[2]);else if(/^(1303|532)$/.test(t))e[t]=0;else{var a=new Promise(((f,a)=>r=e[t]=[f,a]));f.push(r[2]=a);var d=o.p+o.u(t),c=new Error;o.l(d,(f=>{if(o.o(e,t)&&(0!==(r=e[t])&&(e[t]=void 0),r)){var a=f&&("load"===f.type?"missing":f.type),d=f&&f.target&&f.target.src;c.message="Loading chunk "+t+" failed.\n("+a+": "+d+")",c.name="ChunkLoadError",c.type=a,c.request=d,r[1](c)}}),"chunk-"+t,t)}},o.O.j=t=>0===e[t];var t=(t,f)=>{var r,a,d=f[0],c=f[1],b=f[2],n=0;if(d.some((t=>0!==e[t]))){for(r in c)o.o(c,r)&&(o.m[r]=c[r]);if(b)var i=b(o)}for(t&&t(f);n{"use strict";var e,f,t,r,d,a={},c={};function o(e){var f=c[e];if(void 0!==f)return f.exports;var t=c[e]={id:e,loaded:!1,exports:{}};return a[e].call(t.exports,t,t.exports,o),t.loaded=!0,t.exports}o.m=a,o.c=c,e=[],o.O=(f,t,r,d)=>{if(!t){var a=1/0;for(i=0;i=d)&&Object.keys(o.O).every((e=>o.O[e](t[b])))?t.splice(b--,1):(c=!1,d0&&e[i-1][2]>d;i--)e[i]=e[i-1];e[i]=[t,r,d]},o.n=e=>{var f=e&&e.__esModule?()=>e.default:()=>e;return o.d(f,{a:f}),f},t=Object.getPrototypeOf?e=>Object.getPrototypeOf(e):e=>e.__proto__,o.t=function(e,r){if(1&r&&(e=this(e)),8&r)return e;if("object"==typeof e&&e){if(4&r&&e.__esModule)return e;if(16&r&&"function"==typeof e.then)return e}var d=Object.create(null);o.r(d);var a={};f=f||[null,t({}),t([]),t(t)];for(var c=2&r&&e;"object"==typeof c&&!~f.indexOf(c);c=t(c))Object.getOwnPropertyNames(c).forEach((f=>a[f]=()=>e[f]));return a.default=()=>e,o.d(d,a),d},o.d=(e,f)=>{for(var t in f)o.o(f,t)&&!o.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:f[t]})},o.f={},o.e=e=>Promise.all(Object.keys(o.f).reduce(((f,t)=>(o.f[t](e,f),f)),[])),o.u=e=>"assets/js/"+({53:"935f2afb",916:"a57d321a",928:"696a412b",931:"14f1d27f",966:"6c6cf206",1028:"80b5be58",1043:"c3c15305",1257:"76d0d1d8",1455:"d03751be",1909:"b2327a6c",2147:"1b039142",2229:"f012f959",2880:"9b824c8f",3106:"fd5e6f38",3922:"08714d8c",3953:"7a87d372",4007:"d9378b29",4195:"c4f5d8e4",4896:"85f318fb",5089:"8f68e2ce",5171:"61fcde8c",5307:"6f2832ad",5505:"92a77eef",5519:"c24ec994",5649:"c0fe6564",5767:"1d042041",5893:"d04964af",6971:"c377a04b",7107:"be6d912d",7221:"710eddd2",7330:"8f51b104",7918:"17896441",7920:"1a4e3797",8172:"e848be99",8403:"25848ff4",8529:"ac5280f2",8687:"50751b0a",8769:"2d986b69",9071:"354f5e12",9255:"9b35c4f5",9514:"1be78505",9690:"3f8274eb",9921:"4f085710",9985:"8ba33b25"}[e]||e)+"."+{53:"eaa09a8c",916:"7b1da2dc",928:"30d5fb90",931:"e67f3f33",966:"4874a857",1028:"7a80df6d",1043:"0d717cd1",1257:"fef871bb",1455:"3d85882f",1909:"2d13b65b",2147:"34999ad0",2229:"ad12eb4f",2880:"1c11dbd9",3106:"65b6ada4",3922:"8066bd98",3953:"7e5409a8",4007:"6db302b8",4195:"75997564",4698:"8c4037a9",4896:"18658faf",4972:"9c4c5fed",5089:"68e819b0",5171:"4dd88737",5307:"e5b5393c",5505:"3834a1d4",5519:"1b981edd",5649:"fc79d8f6",5767:"3353ac3b",5893:"dad4b03c",6780:"2e464230",6945:"46b11133",6971:"dee11c26",7107:"6d137fe3",7221:"97c3fcd9",7330:"a7e302fa",7918:"e1ad11d7",7920:"2adc3808",8172:"fe19ea8a",8403:"57f5c5cf",8529:"23c0bab4",8687:"5ac1ed00",8769:"356337e0",8894:"2f96187b",9071:"28413fb0",9255:"4724485f",9514:"b5adb11b",9690:"7b2c5f8f",9921:"99943333",9985:"993fc35e"}[e]+".js",o.miniCssF=e=>{},o.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),o.o=(e,f)=>Object.prototype.hasOwnProperty.call(e,f),r={},d="cogment-doc:",o.l=(e,f,t,a)=>{if(r[e])r[e].push(f);else{var c,b;if(void 0!==t)for(var n=document.getElementsByTagName("script"),i=0;i{c.onerror=c.onload=null,clearTimeout(s);var d=r[e];if(delete r[e],c.parentNode&&c.parentNode.removeChild(c),d&&d.forEach((e=>e(t))),f)return f(t)},s=setTimeout(l.bind(null,void 0,{type:"timeout",target:c}),12e4);c.onerror=l.bind(null,c.onerror),c.onload=l.bind(null,c.onload),b&&document.head.appendChild(c)}},o.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},o.p="/",o.gca=function(e){return e={17896441:"7918","935f2afb":"53",a57d321a:"916","696a412b":"928","14f1d27f":"931","6c6cf206":"966","80b5be58":"1028",c3c15305:"1043","76d0d1d8":"1257",d03751be:"1455",b2327a6c:"1909","1b039142":"2147",f012f959:"2229","9b824c8f":"2880",fd5e6f38:"3106","08714d8c":"3922","7a87d372":"3953",d9378b29:"4007",c4f5d8e4:"4195","85f318fb":"4896","8f68e2ce":"5089","61fcde8c":"5171","6f2832ad":"5307","92a77eef":"5505",c24ec994:"5519",c0fe6564:"5649","1d042041":"5767",d04964af:"5893",c377a04b:"6971",be6d912d:"7107","710eddd2":"7221","8f51b104":"7330","1a4e3797":"7920",e848be99:"8172","25848ff4":"8403",ac5280f2:"8529","50751b0a":"8687","2d986b69":"8769","354f5e12":"9071","9b35c4f5":"9255","1be78505":"9514","3f8274eb":"9690","4f085710":"9921","8ba33b25":"9985"}[e]||e,o.p+o.u(e)},(()=>{var e={1303:0,532:0};o.f.j=(f,t)=>{var r=o.o(e,f)?e[f]:void 0;if(0!==r)if(r)t.push(r[2]);else if(/^(1303|532)$/.test(f))e[f]=0;else{var d=new Promise(((t,d)=>r=e[f]=[t,d]));t.push(r[2]=d);var a=o.p+o.u(f),c=new Error;o.l(a,(t=>{if(o.o(e,f)&&(0!==(r=e[f])&&(e[f]=void 0),r)){var d=t&&("load"===t.type?"missing":t.type),a=t&&t.target&&t.target.src;c.message="Loading chunk "+f+" failed.\n("+d+": "+a+")",c.name="ChunkLoadError",c.type=d,c.request=a,r[1](c)}}),"chunk-"+f,f)}},o.O.j=f=>0===e[f];var f=(f,t)=>{var r,d,a=t[0],c=t[1],b=t[2],n=0;if(a.some((f=>0!==e[f]))){for(r in c)o.o(c,r)&&(o.m[r]=c[r]);if(b)var i=b(o)}for(f&&f(t);n