Skip to content

Commit 5ee93e4

Browse files
twindebanktwindebank
committed
[resources] types for resource types
1 parent 9618953 commit 5ee93e4

File tree

3 files changed

+224
-0
lines changed

3 files changed

+224
-0
lines changed

‎resource_attribute.go‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
package client
2+
3+
// Attribute describes an attribute available when accessing a resource of a given type.
4+
type Attribute struct {
5+
// Path expression to read this attribute from a resource payload.
6+
Path string
7+
8+
// Type of the attribute. It doesn't match exactly to action parameter types
9+
// because JSON doesn't differentiate between integers and floating point
10+
// numbers so it's up to interpretation.
11+
Type AttributeType
12+
13+
// Cardinality determines how many values would be returned when applying the
14+
// given JSONPath. Only attributes with a cardinality of "one" can be used as
15+
// tool parameter values.
16+
Cardinality AttributeCardinality
17+
18+
// Description is an optional human-readable description of the attribute.
19+
Description string
20+
21+
// IsTopLevel is true if the attribute is a top-level field (direct child of the root).
22+
IsTopLevel bool
23+
24+
// Name is the name of the field, e.g.:
25+
// - "id" for `$.id`
26+
// - "quantity" for `$.items[*].quantity`
27+
Name string
28+
}
29+
30+
// AttributeCardinality determines how many values would be returned when
31+
// applying an attribute's JSONPath to a resource payload.
32+
type AttributeCardinality string
33+
34+
const (
35+
// AttributeCardinalityOne means the attribute represents one value (e.g.
36+
// `$.id` or `$.name`).
37+
AttributeCardinalityOne AttributeCardinality = "one"
38+
39+
// AttributeCardinalityMany means the attribute represents many values (e.g.
40+
// `$.items[*].quantity`).
41+
AttributeCardinalityMany AttributeCardinality = "many"
42+
)
43+
44+
// AttributeType describes the data type of the attribute.
45+
type AttributeType string
46+
47+
const (
48+
// AttributeTypeString means the attribute is a string.
49+
AttributeTypeString AttributeType = "string"
50+
51+
// AttributeTypeDate means the attribute is a date in the string form:
52+
// YYYY-MM-DD.
53+
AttributeTypeDate AttributeType = "date"
54+
55+
// AttributeTypeTimestamp means the attribute is a timestamp in the RFC3339 form.
56+
AttributeTypeTimestamp AttributeType = "timestamp"
57+
58+
// AttributeTypeBoolean means the attribute is a boolean value.
59+
AttributeTypeBoolean AttributeType = "boolean"
60+
61+
// AttributeTypeNumber means the attribute is a numeric value. JSON doesn't
62+
// differentiate between integers and floating point numbers, so it's up to
63+
// the user to interpret this.
64+
AttributeTypeNumber AttributeType = "number"
65+
66+
// AttributeTypeArray means the attribute is an array of primitive values.
67+
//
68+
// Note: an array of primitive values will still have a cardinality of "one"
69+
// because there is one value available (the array itself).
70+
AttributeTypeArray AttributeType = "array"
71+
72+
// AttributeTypeComplex means the attribute could be many types, which we don't
73+
// support yet.
74+
AttributeTypeComplex AttributeType = "complex"
75+
)

‎resource_schema.go‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
package client
2+
3+
import "encoding/json"
4+
5+
// Schema of data related to a resource.
6+
type Schema struct {
7+
// Raw is the raw schema data.
8+
// - inferred from the data payloads
9+
// - updated asynchronously as data is fetched
10+
// - can be unmarshalled into a jsonschema.Schema (use Parse method)
11+
Raw json.RawMessage
12+
13+
// Attributes is a list of attributes derived from the schema. Only leaf properties are included in this list,
14+
// container objects and arrays themselves are not included as separate attributes.
15+
//
16+
// For example, given a schema with:
17+
// {
18+
// "properties": {
19+
// "name": { "type": "string" },
20+
// "address": {
21+
// "type": "object",
22+
// "properties": {
23+
// "street": { "type": "string" },
24+
// "city": { "type": "string" }
25+
// }
26+
// },
27+
// "skills": {
28+
// "type": "array",
29+
// "items": {
30+
// "type": "object",
31+
// "properties": {
32+
// "name": { "type": "string" },
33+
// "level": { "type": "string" }
34+
// }
35+
// }
36+
// }
37+
// }
38+
// }
39+
//
40+
// The resulting attributes would be:
41+
// - $.name (string)
42+
// - $.address.street (string)
43+
// - $.address.city (string)
44+
// - $.skills[*].name (string)
45+
// - $.skills[*].level (string)
46+
//
47+
// Note that $.address and $.skills are not included as separate attributes.
48+
// Attributes are sorted alphabetically by JSONPath.
49+
Attributes []Attribute
50+
}

‎resource_type.go‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
package client
2+
3+
import "time"
4+
5+
type ResourceType struct {
6+
// ID is a generated ID for the resource type.
7+
ID string
8+
9+
// DisplayName is a freetext human-readable name for the resource type.
10+
DisplayName string
11+
12+
// Description is an optional freetext human-readable description of the resource type.
13+
Description string
14+
15+
// Scope determines when in the conversation the resource is fetched and used.
16+
Scope Scope
17+
18+
// RefreshStrategy determines how often the resource is re-fetched.
19+
RefreshStrategy RefreshStrategy
20+
21+
// SourceConfig defines how the resource is fetched. If not set, the type can still be used in testing environments
22+
// with mocked data.
23+
SourceConfig *SourceConfig
24+
25+
// Schema is the JSON schema for the resource type, optionally including attribute descriptions from the source if
26+
// IncludeDescriptions is true on read.
27+
Schema *Schema
28+
29+
// IsEnabled indicates whether the resource type has been configured as enabled or not.
30+
IsEnabled bool
31+
32+
Created time.Time
33+
Updated time.Time
34+
}
35+
type SourceConfig struct {
36+
// SourceID identifies the source which should be used to fetch the resource data.
37+
SourceID string
38+
39+
// Attributes defines the *top-level* fields names to be used from the source data. Eg. for a payload like this:
40+
//
41+
// ```
42+
// {
43+
// "id": 123,
44+
// "name": "foo",
45+
// "items": [
46+
// {
47+
// "id": 1,
48+
// "name": "bar"
49+
// },
50+
// {
51+
// "id": 2,
52+
// "name": "baz"
53+
// }
54+
// ],
55+
// "nested": {
56+
// "id": 456,
57+
// "name": "qux"
58+
// }
59+
// }
60+
// ```
61+
//
62+
// The following attributes would be valid:
63+
// - "id"
64+
// - "name"
65+
// - "items"
66+
// - "nested"
67+
// The following attributes would be invalid:
68+
// - "items[*].id"
69+
// - "nested.id"
70+
Attributes []string
71+
72+
// Cache determines how long we'll consider data from the source be valid before refreshing it. It's either a
73+
// duration string (e.g. "5m") or CacheNever if the resource is refreshed on every turn. The default is 1 minute.
74+
Cache string
75+
}
76+
77+
// CacheNever means the pull resource will be refreshed on every turn of the
78+
// conversation.
79+
const CacheNever = "never"
80+
81+
type Scope string
82+
83+
const (
84+
// ScopeGlobal means the resource is available throughout the conversation and in all procedures.
85+
ScopeGlobal Scope = "global"
86+
87+
// ScopeLocal means the resource is available only in procedures that explicitly use it, only fetched when it’s used.
88+
ScopeLocal Scope = "local"
89+
)
90+
91+
type RefreshStrategy string
92+
93+
const (
94+
// RefreshStrategyDynamic means the resource value can change, so this is re-fetched throughout the conversation.
95+
RefreshStrategyDynamic RefreshStrategy = "dynamic"
96+
97+
// RefreshStrategyStatic means the resource is fetched once at the start of the conversation (global) or when it’s first used in a procedure (local).
98+
RefreshStrategyStatic RefreshStrategy = "static"
99+
)

0 commit comments

Comments
 (0)