Skip to content

Commit 11cd326

Browse files
twindebanktwindebank
authored
[resources] types for resource types (#51)
2 parents f912221 + b4e2535 commit 11cd326

File tree

3 files changed

+222
-0
lines changed

3 files changed

+222
-0
lines changed

‎resource_attribute.go‎

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

‎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 `json:"raw"`
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 `json:"attributes"`
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 `json:"id"`
8+
9+
// DisplayName is a freetext human-readable name for the resource type.
10+
DisplayName string `json:"display_name"`
11+
12+
// Description is an optional freetext human-readable description of the resource type.
13+
Description string `json:"description"`
14+
15+
// Scope determines when in the conversation the resource is fetched and used.
16+
Scope Scope `json:"scope"`
17+
18+
// RefreshStrategy determines how often the resource is re-fetched.
19+
RefreshStrategy RefreshStrategy `json:"refresh_strategy"`
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 `json:"source_config,omitempty"`
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 `json:"schema,omitempty"`
28+
29+
// IsEnabled indicates whether the resource type has been configured as enabled or not.
30+
IsEnabled bool `json:"is_enabled"`
31+
32+
Created time.Time `json:"created"`
33+
Updated time.Time `json:"updated"`
34+
}
35+
type SourceConfig struct {
36+
// SourceID identifies the source which should be used to fetch the resource data.
37+
SourceID string `json:"source_id"`
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 `json:"attributes"`
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 `json:"cache"`
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)