Jido.AI.Skill.ResourceProvider (Jido AI v2.4.0)

Copy Markdown View Source

Invokes and validates host callbacks that provide runtime skill resources.

Providers are only used for runtime specs supplied through Agent Skills integration. Filesystem skills continue to use Jido.AI.Skill.Resources.

Supported provider forms are:

  • fn request, context -> result end
  • {Module, :function}
  • {Module, :function, extra_args}

Providers receive canonical requests:

%{operation: :list, skill: spec, policy: policy}
%{operation: :load, skill: spec, resource_id: resource_id, policy: policy}

Valid results are:

{:ok, %{resources: [%{id: id, name: name, size: size}], complete: boolean()}}
{:ok, %{resource_id: resource_id, content: text, size: non_neg_integer()}}
{:error, term()}

List entries require id, name, and size. Optional fields are type, modified, mime_type, and metadata. The resources field is the complete aggregate listing. scripts, references, and assets are filtered views of the same entries, so entries intentionally appear in both the aggregate list and their typed view. IDs are scoped to the activated skill and provider binding. Loading by an ID that was not present in the activated post-policy listing is rejected before the provider is called, including when the provider reported an incomplete listing.

Jido validates and normalizes every result, reapplies ResourcePolicy, rejects entries that cannot be encoded for listing, rejects malformed identifiers and binary content unless explicitly allowed, and invokes the provider on every resource load so content remains fresh. Listing truncation is ordered: the first entry that violates count, declared-size, or encoded-listing limits is excluded, as is everything after it. Resource IDs are opaque and are never parsed, normalized, joined, sorted, or interpreted.

Summary

Types

binding()
provider()
resource_info()
resource_listing()

Functions

list(provider, spec, policy, context)

Lists provider-backed resources with opaque IDs.

load(provider, spec, resource_id, policy, context)

Loads one provider-backed resource by opaque ID.

validate(provider)

Validates a provider form.

Types

binding()

@type binding() :: %{provider: provider(), context: map()}

provider()

@type provider() ::
  (map(), map() -> term()) | {module(), atom()} | {module(), atom(), [term()]}

resource_info()

@type resource_info() :: %{
  :id => String.t(),
  :name => String.t(),
  :size => non_neg_integer(),
  :modified => DateTime.t(),
  optional(:type) => atom() | String.t() | nil,
  optional(:mime_type) => String.t() | nil,
  optional(:metadata) => map()
}

resource_listing()

@type resource_listing() :: %{
  resources: [resource_info()],
  scripts: [resource_info()],
  references: [resource_info()],
  assets: [resource_info()],
  complete: boolean(),
  truncated: boolean(),
  truncation_reasons: [atom()],
  limits: map()
}

Functions

list(provider, spec, policy, context)

@spec list(
  provider(),
  Jido.AI.Skill.Spec.t(),
  Jido.AI.Skill.ResourcePolicy.t(),
  map()
) ::
  {:ok, resource_listing()} | {:error, term()}

Lists provider-backed resources with opaque IDs.

load(provider, spec, resource_id, policy, context)

@spec load(
  provider(),
  Jido.AI.Skill.Spec.t(),
  String.t(),
  Jido.AI.Skill.ResourcePolicy.t(),
  map()
) ::
  {:ok, Jido.AI.Skill.Resources.loaded_resource()} | {:error, term()}

Loads one provider-backed resource by opaque ID.

Binary responses require binary: :allow, filename, and mime_type.

validate(provider)

@spec validate(provider() | nil) :: {:ok, provider() | nil} | {:error, term()}

Validates a provider form.