@spec all_simple_types?([map()]) :: boolean()

Check whether all sub-schemas in a composition have simple, promptable types (string, integer, number, boolean).

@spec merge_schemas([map()]) :: map()

Merge a list of schemas into a single schema. Used for allOf resolution.

Combines type (last wins), properties (deep merge), required (union), and enum (intersection). Other keys are merged with last-wins semantics.

@spec normalize_schema(map()) :: map()

Recursively normalize a schema map to string keys, including any composition keyword sub-schemas.

@spec normalize_spec(map()) :: {:ok, map()} | {:error, atom(), String.t()}

Normalize a parsed JSON spec into a canonical map with string keys.

Returns {:ok, %{properties: map, required: list}} or {:error, reason, msg}.

@spec nullable_schema?(String.t(), [map()]) :: {:nullable, map()} | :not_nullable

Check whether a composition schema represents a nullable type -- i.e., anyOf/oneOf with exactly two sub-schemas where one is {type: "null"}.

Returns {:nullable, non_null_schema} or :not_nullable.

@spec param_list(map() | %{properties: map(), required: [binary()]}) ::
  {:ok, list()} | {:error, atom(), String.t()}

Return a deterministic parameter list: [{name, schema, required?}].

@spec resolve_schema_type(map()) ::
  {:ok, String.t()}
  | {:composition, String.t(), [map()]}
  | {:error, :unresolvable}

Resolve a schema to its effective type. Returns the type string for flat schemas, or {:composition, keyword, sub_schemas} for composition schemas.

@spec validate_all_args(map() | %{properties: map(), required: [binary()]}, map()) ::
  {:ok, map()}
  | {:error, {:missing_required, [binary()]}}
  | {:error, atom(), any()}

Validate that required keys are present and coerce all provided values.

Returns {:ok, coerced_map} or {:error, {:missing_required, keys}} or {:error, {:invalid, reason}}.

@spec validate_and_coerce_param(map(), any()) ::
  {:ok, any()} | {:error, atom(), String.t()}

Validate and coerce a single parameter value according to schema.

Supports flat type-based schemas and composition keywords (anyOf, oneOf, allOf). Resolution order: type > anyOf > oneOf > allOf.

Returns {:ok, coerced} or {:error, reason, message}.

@spec validate_json_args(map(), map()) ::
  {:ok, map()}
  | {:error, :missing_argument, binary()}
  | {:error, :invalid_argument, binary()}

Validate and coerce tool call arguments against a tool spec.

Accepts the full tool spec (as returned by module.spec()), a raw spec with a parameters key, or a pre-normalized %{properties: ..., required: ...}.

Returns {:ok, coerced_args} or an AI.Tools.args_error().

@spec validate_prefilled_args(
  map() | %{properties: map(), required: [binary()]},
  map()
) ::
  {:ok, map()} | {:error, atom(), any()}

Validate a map of prefilled args against a spec. Rejects unknown keys and coerces known keys. Returns {:ok, coerced_map} or {:error, reason, message}.