aifunctions

type AiClassifyOptions struct {
	// When true, includes a per-label confidence score in the response.
	EnableConfidenceScores bool `json:"enable_confidence_scores,omitempty"`
	// When true, includes a rationale explaining each classification in the
	// response.
	EnableRationales bool `json:"enable_rationales,omitempty"`
	// Natural-language guidance that steers how the text is classified (up to
	// 20,000 characters).
	Instructions string `json:"instructions,omitempty"`
	// When true, allows more than one label to be returned per input.
	Multilabel bool `json:"multilabel,omitempty"`
	// The function version to invoke. Defaults to the latest version. Supported
	// versions: ["2.1"].
	Version string `json:"version,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiClassifyRequest struct {
	// The content to classify. It accepts a plain string or the response object
	// of [ai_parse_document](:method:AiFunctions/AiParseDocument).
	Content json.RawMessage `json:"content"`
	// The label set to classify as. Either a JSON array of label strings (e.g.
	// ["spam", "not_spam"]), or a JSON object mapping each label to a
	// description (e.g. {"spam": "unsolicited bulk message", "not_spam": "a
	// legitimate message"}). Accepts 2 to 500 labels, each 1 to 100 characters.
	Labels json.RawMessage `json:"labels"`
	// Function options. Omitted fields fall back to their documented defaults.
	Options *AiClassifyOptions `json:"options,omitempty"`
}

type AiClassifyResponse struct {
	// Additional metadata returned by AI Classify.
	Metadata *AiClassifyResponseMetadata `json:"metadata,omitempty"`
	// The function result as a JSON value. An array of per-label objects: one
	// element in single-label mode (the default), or multiple elements when
	// `multilabel` is true. When `enable_confidence_scores` and
	// `enable_rationales` are true, `confidence_score` and `rationale` are
	// included in each response value, respectively.
	Response *json.RawMessage `json:"response,omitempty"`
}

type AiClassifyResponseMetadata struct {
	// The resolved function version.
	Version string `json:"version,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiDecideOptions struct {
	// The function API version to invoke. Defaults to "1.0". Supported
	// versions: ["1.0"].
	Version string `json:"version,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiDecideRequest struct {
	// Function options. Omitted fields fall back to their documented defaults.
	Options *AiDecideOptions `json:"options,omitempty"`
	// A JSON object mapping question IDs to their definitions. Choose a
	// nonempty string for each ID; its answer is returned with the same ID in
	// `response.answers`.
	//
	// Each definition is an object with the required fields `type` and
	// `instructions`. The `criteria` field is optional for the type `noul` but
	// is required for the types `choice` and `score`.
	//
	// The `instructions` field describes the judgment to make and can be a
	// string, object, or array. Use an object or array to include supporting
	// context alongside the instructions.
	//
	// The `type` can be one of:
	//
	// - `choice`: Selects one option from a defined set. Requires `criteria` to
	// be an object mapping 1 to 255 nonempty option names to descriptions. The
	// criteria description can be a string, object, array, or null when the
	// name needs no additional detail. For example:
	//
	// “`json { "team": { "type": "choice", "instructions": "Which team should
	// handle this ticket?", "criteria": { "billing": "Payments, charges, and
	// refunds", "technical_support": null } } } “`
	//
	// - `noul`: Estimates the probability that the answer to a true-or-false
	// question is true. `criteria` can take the fields `true` or `false`, or
	// both, with descriptions that are strings, objects, or arrays. Omit
	// `criteria` to use the question alone. For example, both of the following
	// are valid:
	//
	// “`json { "escalate": { "type": "noul", "instructions": "Does this ticket
	// need escalation?", "criteria": { "true": "Suspected fraud or an exception
	// to standard policy", "false": "A routine issue frontline support can
	// resolve" } } } “`
	//
	// or
	//
	// “`json { "escalate": { "type": "noul", "instructions": "Does this ticket
	// need escalation?" } } “`
	//
	// - `score`: Rates the state on an ordered scale. Requires `criteria` to be
	// an array of 2 to 10 level descriptions, ordered from low to high.
	// Descriptions can be strings, objects, or arrays. Array positions define
	// levels starting at 0. For example:
	//
	// “`json { "urgency": { "type": "score", "instructions": "How urgent is
	// this ticket?", "criteria": [ "Routine: can wait a few days",
	// "Time-sensitive: needs attention today", "Critical: needs immediate
	// action" ] } } “`
	Questions json.RawMessage `json:"questions"`
	// A string, JSON object, or array containing the content, related context,
	// and examples needed to answer the provided questions. For example,
	// provide a support message, a conversation, or records describing the
	// current state of an application. All questions receive this same state.
	State json.RawMessage `json:"state"`
}

type AiDecideResponse struct {
	// Metadata identifying the function API version used for this request.
	Metadata *AiDecideResponseMetadata `json:"metadata,omitempty"`
	// A JSON object containing an `answers` map with one answer for each
	// question, keyed by the same IDs as `questions`.
	//
	// Each answer has a `type` matching its question and the following fields:
	//
	// - `choice`: choice is the highest-probability option from `criteria`.
	// `probabilities` maps every option name to its probability. `confidence`
	// is a number from 0 to 1 indicating how well the state supports the
	// assessment. The `probabilities` values sum to 1. For example:
	//
	// “`json { "answers": { "team": { "type": "choice", "choice": "billing",
	// "probabilities": { "billing": 0.85, "technical_support": 0.15 },
	// "confidence": 0.9 } } } “`
	//
	// - `noul`: `probability` is a number from 0 to 1 estimating the
	// probability that the answer is true. For example:
	//
	// “`json { "answers": { "escalate": { "type": "noul", "probability": 0.8 }
	// } } “`
	//
	// - `score`: score is the probability-weighted mean of the zero-based level
	// indices. It can fall between levels, from 0 to the number of levels minus
	// 1. `probabilities` maps each level index to its probability, and `legend`
	// maps each index to its original description. Both maps use string keys
	// such as "0", "1", and "2". `confidence` is a number from 0 to 1
	// indicating how well the state supports the assessment. The
	// `probabilities` values sum to 1. For example:
	//
	// “`json { "answers": { "urgency": { "type": "score", "score": 1.6,
	// "probabilities": { "0": 0.1, "1": 0.2, "2": 0.7 }, "legend": { "0":
	// "Routine: can wait a few days", "1": "Time-sensitive: needs attention
	// today", "2": "Critical: needs immediate action" }, "confidence": 0.85 } }
	// } “`
	Response *json.RawMessage `json:"response,omitempty"`
}

type AiDecideResponseMetadata struct {
	// The function API version used to evaluate the request.
	Version string `json:"version,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiExtractBbox struct {
	// Pixel coordinates on the page image as [x0, y0, x1, y1].
	Coord []int64 `json:"coord,omitempty"`
	// 0-based page index the box is on.
	PageId int64 `json:"page_id,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiExtractCitation struct {
	// Bounding boxes locating the citation on the source pages; set for bbox
	// citations.
	Bbox []AiExtractBbox `json:"bbox,omitempty"`
	// Integer matching a citation_ids entry on an extracted field.
	Id int64 `json:"id,omitempty"`
	// Inclusive 0-based character offset into the input string; set for span
	// citations.
	Start int64 `json:"start,omitempty"`
	// Exclusive 0-based character offset into the input string; set for span
	// citations.
	Stop int64 `json:"stop,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiExtractOptions struct {
	// When true, includes citation metadata locating each extracted value in
	// the source. Depending on the type of input, citations can be one of two
	// types:
	//
	// For raw text (STRING) inputs, a citation is a span of text in the
	// original input. Each object in `metadata.citations` has an `id` (integer
	// matching a `citation_ids` entry on a field), a `start` (inclusive 0-based
	// character offset into the input string), and a `stop` (exclusive 0-based
	// character offset into the input string).
	//
	// For PDF documents and images (when using ai_extract downstream of
	// ai_parse_document), a citation is a bounding box in the original input.
	// Each object in `metadata.citations` has an `id` (integer matching a
	// `citation_ids` entry on a field) and a `bbox` (array of {coord, page_id}
	// objects, identical in shape to element.bbox in ai_parse_document output;
	// coord is pixel coordinates on the page image as [x0, y0, x1, y1], and
	// page_id is a 0-based page index).
	EnableCitations bool `json:"enable_citations,omitempty"`
	// When true, includes a per-field confidence score in the response.
	EnableConfidenceScores bool `json:"enable_confidence_scores,omitempty"`
	// Natural-language guidance that steers how data is extracted (up to 20,000
	// characters).
	Instructions string `json:"instructions,omitempty"`
	// Extraction mode. Supported modes: "precision" — more powerful
	// extraction for complex schemas, long documents, and reasoning-heavy
	// extractions. Defaults to none (standard extraction).
	Mode string `json:"mode,omitempty"`
	// The function version to invoke. Defaults to the latest version. Supported
	// versions: ["2.1"].
	Version string `json:"version,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiExtractRequest struct {
	// The text to extract from. It accepts a plain string or the response
	// object of [ai_parse_document](:method:AiFunctions/AiParseDocument).
	Content json.RawMessage `json:"content"`
	// Function options. Omitted fields fall back to their documented defaults.
	Options *AiExtractOptions `json:"options,omitempty"`
	// The extraction schema defining the fields to extract. Either a JSON array
	// of field names, assumed to be strings (e.g. ["company", "valuation"]), or
	// a JSON object mapping each field to its type/description/nullability
	// (e.g. {"company": {"type": "string", "description": "the company
	// name"}}). Accepts up to 256 fields, 12 levels of nesting, and 500 enum
	// values. Supported field types are string, integer, number, boolean, and
	// enum.
	Schema json.RawMessage `json:"schema"`
}

type AiExtractResponse struct {
	// Additional metadata returned by AI Extract.
	Metadata *AiExtractResponseMetadata `json:"metadata,omitempty"`
	// The function result as a JSON value. When `enable_confidence_scores` and
	// `enable_citations` are true, `confidence` and `citation_ids` are included
	// in each response field, respectively.
	Response *json.RawMessage `json:"response,omitempty"`
}

type AiExtractResponseMetadata struct {
	// How the source was chunked for citation offsets (span for text input,
	// bbox for parsed-document input); present when citations are enabled.
	ChunkType string `json:"chunk_type,omitempty"`
	// Citation objects locating each result in the source; present when
	// citations are enabled.
	Citations []AiExtractCitation `json:"citations,omitempty"`
	// The resolved extraction mode; present when a non-default mode was used.
	Mode string `json:"mode,omitempty"`
	// The resolved function version.
	Version string `json:"version,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiFunctionsAPI struct {
	// contains filtered or unexported fields
}

type AiFunctionsInterface interface {

	// Classifies content according to a set of provided labels. For REST API
	// requests, the default rate limit is 1,200 requests per minute per workspace.
	// Contact your Databricks account team to request a higher limit.
	AiClassify(ctx context.Context, request AiClassifyRequest) (*AiClassifyResponse, error)

	// Turn text and structured data into decisions your application can use. Define
	// questions and criteria to choose an option, estimate a probability, or assign
	// a score given a provided state.
	AiDecide(ctx context.Context, request AiDecideRequest) (*AiDecideResponse, error)

	// Extracts structured data from text and documents according to a provided
	// schema. For REST API requests, the default rate limit is 120 requests per
	// minute per workspace. Contact your Databricks account team to request a
	// higher limit.
	AiExtract(ctx context.Context, request AiExtractRequest) (*AiExtractResponse, error)

	// Parse structured content from unstructured documents.
	AiParseDocument(ctx context.Context, request AiParseDocumentRequest) (*AiParseDocumentResponse, error)
}

type AiParseDocumentFileMetadata struct {
	// Last-modified timestamp of the source file, as an HTTP date string.
	FileModificationTime string `json:"file_modification_time,omitempty"`
	// Base name of the source file.
	FileName string `json:"file_name,omitempty"`
	// Unity Catalog volume path of the source file.
	FilePath string `json:"file_path,omitempty"`
	// Size of the source file in bytes.
	FileSize int64 `json:"file_size,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiParseDocumentOptions struct {
	// Element types for which an AI-generated description is produced. Use "*"
	// (default) to generate descriptions for all supported element types,
	// "figure" to generate them for figures only, or "" (empty string) to
	// generate none. Only figure descriptions are supported for version "2.0",
	// so "*" and "figure" produce the same behavior.
	DescriptionElementTypes string `json:"description_element_types,omitempty"`
	// Unity Catalog volume path where rendered page and element images are
	// written.
	ImageOutputPath string `json:"image_output_path,omitempty"`
	// Pages to parse (1-indexed), as a comma-separated list of page numbers or
	// ranges (e.g. "1,3,5-10").
	PageRange string `json:"page_range,omitempty"`
	// The ai_parse_document output schema version. Supported value: "2.0".
	Version string `json:"version,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiParseDocumentPageError struct {
	// Message describing why the page failed.
	ErrorMessage string `json:"error_message,omitempty"`
	// 0-based index of the page that failed.
	PageId int64 `json:"page_id,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type AiParseDocumentRequest struct {
	// The document to parse, given as a Unity Catalog volume path to the source
	// file (the REST API accepts only a UC volume path, not inline binary
	// data). Supported formats: PDF, DOCX, DOC, PPTX, PPT, JPG, JPEG, PNG,
	// TIFF. Accepts up to 100 pages and 100 MB per document.
	Content string `json:"content"`
	// Function options. Omitted fields fall back to their documented defaults.
	Options *AiParseDocumentOptions `json:"options,omitempty"`
}

type AiParseDocumentResponse struct {
	// The parsed document as a JSON value, containing the extracted pages and
	// elements.
	Document *json.RawMessage `json:"document,omitempty"`
	// Per-page partial-failure details; present when the request succeeds (2xx)
	// but individual pages fail.
	ErrorStatus []AiParseDocumentPageError `json:"error_status,omitempty"`
	// Additional metadata returned by AI Parse Document.
	Metadata *AiParseDocumentResponseMetadata `json:"metadata,omitempty"`
}

type AiParseDocumentResponseMetadata struct {
	// Describes the source file; present only for file-path input.
	FileMetadata *AiParseDocumentFileMetadata `json:"file_metadata,omitempty"`
	// Unique identifier for the parse request.
	Id string `json:"id,omitempty"`
	// The resolved function version.
	Version string `json:"version,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}