[resources] types for resource types

resource_attribute.go

@@ -0,0 +1,73 @@
+package client
+
+// Attribute describes an attribute available when accessing a resource of a given type.
+type Attribute struct {
+	// Path expression to read this attribute from a resource payload.
+	Path string
+
+	// Type describes the data type of the attribute.
+	Type AttributeType
+
+	// Cardinality determines how many values would be returned when applying the
+	// given JSONPath. Only attributes with a cardinality of "one" can be used as
+	// tool parameter values.
+	Cardinality AttributeCardinality
+
+	// Description is an optional human-readable description of the attribute.
+	Description string
+
+	// IsTopLevel is true if the attribute is a top-level field (direct child of the root).
+	IsTopLevel bool
+
+	// Name is the name of the field, e.g.:
+	//   - "id" for `$.id`
+	//   - "quantity" for `$.items[*].quantity`
+	Name string
+}
+
+// AttributeCardinality determines how many values would be returned when
+// applying an attribute's JSONPath to a resource payload.
+type AttributeCardinality string
+
+const (
+	// AttributeCardinalityOne means the attribute represents one value (e.g.
+	// `$.id` or `$.name`).
+	AttributeCardinalityOne AttributeCardinality = "one"
+
+	// AttributeCardinalityMany means the attribute represents many values (e.g.
+	// `$.items[*].quantity`).
+	AttributeCardinalityMany AttributeCardinality = "many"
+)
+
+// AttributeType describes the data type of the attribute.
+type AttributeType string
+
+const (
+	// AttributeTypeString means the attribute is a string.
+	AttributeTypeString AttributeType = "string"
+
+	// AttributeTypeDate means the attribute is a date in the string form:
+	// YYYY-MM-DD.
+	AttributeTypeDate AttributeType = "date"
+
+	// AttributeTypeTimestamp means the attribute is a timestamp in the RFC3339 form.
+	AttributeTypeTimestamp AttributeType = "timestamp"
+
+	// AttributeTypeBoolean means the attribute is a boolean value.
+	AttributeTypeBoolean AttributeType = "boolean"
+
+	// AttributeTypeNumber means the attribute is a numeric value. JSON doesn't
+	// differentiate between integers and floating point numbers, so it's up to
+	// the user to interpret this.
+	AttributeTypeNumber AttributeType = "number"
+
+	// AttributeTypeArray means the attribute is an array of primitive values.
+	//
+	// Note: an array of primitive values will still have a cardinality of "one"
+	// because there is one value available (the array itself).
+	AttributeTypeArray AttributeType = "array"
+
+	// AttributeTypeComplex means the attribute could be many types, which we don't
+	// support yet.
+	AttributeTypeComplex AttributeType = "complex"
+)

resource_schema.go

@@ -0,0 +1,50 @@
+package client
+
+import "encoding/json"
+
+// Schema of data related to a resource.
+type Schema struct {
+	// Raw is the raw schema data.
+	// - inferred from the data payloads
+	// - updated asynchronously as data is fetched
+	// - can be unmarshalled into a jsonschema.Schema (use Parse method)
+	Raw json.RawMessage `json:"raw"`
+
+	// Attributes is a list of attributes derived from the schema. Only leaf properties are included in this list,
+	// container objects and arrays themselves are not included as separate attributes.
+	//
+	// For example, given a schema with:
+	//   {
+	//     "properties": {
+	//       "name": { "type": "string" },
+	//       "address": {
+	//         "type": "object",
+	//         "properties": {
+	//           "street": { "type": "string" },
+	//           "city": { "type": "string" }
+	//         }
+	//       },
+	//       "skills": {
+	//         "type": "array",
+	//         "items": {
+	//           "type": "object",
+	//           "properties": {
+	//             "name": { "type": "string" },
+	//             "level": { "type": "string" }
+	//           }
+	//         }
+	//       }
+	//     }
+	//   }
+	//
+	// The resulting attributes would be:
+	//   - $.name (string)
+	//   - $.address.street (string)
+	//   - $.address.city (string)
+	//   - $.skills[*].name (string)
+	//   - $.skills[*].level (string)
+	//
+	// Note that $.address and $.skills are not included as separate attributes.
+	// Attributes are sorted alphabetically by JSONPath.
+	Attributes []Attribute `json:"attributes"`
+}

resource_type.go

@@ -0,0 +1,99 @@
+package client
+
+import "time"
+
+type ResourceType struct {
+	// ID is a generated ID for the resource type.
+	ID string `json:"id"`
+
+	// DisplayName is a freetext human-readable name for the resource type.
+	DisplayName string `json:"display_name"`
+
+	// Description is an optional freetext human-readable description of the resource type.
+	Description string `json:"description"`
+
+	// Scope determines when in the conversation the resource is fetched and used.
+	Scope Scope `json:"scope"`
+
+	// RefreshStrategy determines how often the resource is re-fetched.
+	RefreshStrategy RefreshStrategy `json:"refresh_strategy"`
+
+	// SourceConfig defines how the resource is fetched. If not set, the type can still be used in testing environments
+	// with mocked data.
+	SourceConfig *SourceConfig `json:"source_config,omitempty"`
+
+	// Schema is the JSON schema for the resource type, optionally including attribute descriptions from the source if
+	// IncludeDescriptions is true on read.
+	Schema *Schema `json:"schema,omitempty"`
+
+	// IsEnabled indicates whether the resource type has been configured as enabled or not.
+	IsEnabled bool `json:"is_enabled"`
+
+	Created time.Time `json:"created"`
+	Updated time.Time `json:"updated"`
+}
+type SourceConfig struct {
+	// SourceID identifies the source which should be used to fetch the resource data.
+	SourceID string `json:"source_id"`
+
+	// Attributes defines the *top-level* fields names to be used from the source data. Eg. for a payload like this:
+	//
+	// ```
+	// {
+	//   "id": 123,
+	//   "name": "foo",
+	//   "items": [
+	//     {
+	//       "id": 1,
+	//       "name": "bar"
+	//     },
+	//     {
+	//       "id": 2,
+	//       "name": "baz"
+	//     }
+	//   ],
+	//	"nested": {
+	//     "id": 456,
+	//     "name": "qux"
+	//   }
+	// }
+	// ```
+	//
+	// The following attributes would be valid:
+	//   - "id"
+	//   - "name"
+	//   - "items"
+	//   - "nested"
+	// The following attributes would be invalid:
+	//   - "items[*].id"
+	//   - "nested.id"
+	Attributes []string `json:"attributes"`
+
+	// Cache determines how long we'll consider data from the source be valid before refreshing it. It's either a
+	// duration string (e.g. "5m") or CacheNever if the resource is refreshed on every turn. The default is 1 minute.
+	Cache string `json:"cache"`
+}
+
+// CacheNever means the pull resource will be refreshed on every turn of the
+// conversation.
+const CacheNever = "never"
+
+type Scope string
+
+const (
+	// ScopeGlobal means the resource is available throughout the conversation and in all procedures.
+	ScopeGlobal Scope = "global"
+
+	// ScopeLocal means the resource is available only in procedures that explicitly use it, only fetched when it's used.
+	ScopeLocal Scope = "local"
+)
+
+type RefreshStrategy string
+
+const (
+	// RefreshStrategyDynamic means the resource value can change, so this is re-fetched throughout the conversation.
+	RefreshStrategyDynamic RefreshStrategy = "dynamic"
+
+	// RefreshStrategyStatic means the resource is fetched once at the start of the conversation (global) or when it's first used in a procedure (local).
+	RefreshStrategyStatic RefreshStrategy = "static"
+)