f

TypeScript

const f: () => AxSignatureBuilder & object;

Defined in: https://github.com/ax-llm/ax/blob/5b28f9093bb70863b59459bb6df5062d005bce41/src/ax/dsp/sig.ts#L733

Fluent field builder for creating type-safe signature fields.

The f object provides factory methods for all supported field types, each returning a chainable builder that allows adding constraints and modifiers.

Basic Usage: When called as a function, f() returns a new AxSignatureBuilder for programmatic signature construction. More commonly, use its type methods directly.

Type Methods:

f.string(desc?) - Text content
f.number(desc?) - Numeric values
f.boolean(desc?) - True/false values
f.json(desc?) - Arbitrary JSON objects
f.datetime(desc?) - ISO 8601 datetime strings
f.date(desc?) - Date in YYYY-MM-DD format
f.datetimeRange(desc?) - { start: Date; end: Date } datetime ranges
f.dateRange(desc?) - { start: Date; end: Date } date ranges
f.class(options, desc?) - Classification with predefined choices
f.image(desc?) - Image input (multimodal)
f.audio(desc?) - Audio input
f.file(desc?) - File input
f.url(desc?) - URL strings
f.email(desc?) - Email addresses
f.code(language?, desc?) - Code blocks
f.object(fields, desc?) - Nested object with typed fields

Modifier Methods (chainable):

.optional() - Mark field as optional
.array(desc?) - Convert to array of this type
.internal() - Hide from final output (for intermediate reasoning)
.cache() - Mark for context caching
.min(value) - Minimum length (strings) or value (numbers)
.max(value) - Maximum length (strings) or value (numbers)
.regex(pattern, desc) - Regex validation for strings
.email() - Email format validation for strings
.url() - URL format validation for strings

Type declaration

Name	Type	Description
`audio()`	(`desc?`: `string`) => `AxFluentFieldType`<`"audio"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates an audio field type for audio inputs. Pass audio as base64-encoded data or URLs. Only supported as input fields with models that support audio processing. Note: Cannot be used in nested `f.object()` fields - only as top-level inputs. Example `f.audio('Voice recording to transcribe') f.audio('Audio clip for analysis')`
`boolean()`	(`desc?`: `string`) => `AxFluentFieldType`<`"boolean"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a boolean field type. Booleans represent true/false values. Useful for yes/no questions, flags, and binary decisions. Example `f.boolean('Whether the text contains personally identifiable information') f.boolean('Is the sentiment positive')`
`class()`	<`TOptions`>(`options`: `TOptions`, `desc?`: `string`) => `AxFluentFieldType`<`"class"`, `false`, `TOptions`, `false`, `false`, `undefined`, `false`>	Creates a classification field type with predefined options. The AI will always return exactly one of the provided options. Use `as const` for the options array to get literal type inference. Example `f.class(['positive', 'negative', 'neutral'] as const, 'Sentiment') f.class(['bug', 'feature', 'question', 'docs'] as const, 'Issue type') f.class(['low', 'medium', 'high', 'critical'] as const).optional()`
`code()`	(`language?`: `string`, `desc?`: `string`) => `AxFluentFieldType`<`"code"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a code field type for source code blocks. Code fields preserve formatting and are rendered in code blocks. Optionally specify a language for syntax highlighting context. Example `f.code('typescript', 'Generated TypeScript function') f.code('python', 'Python script to solve the problem') f.code() // Language-agnostic code`
`date()`	(`desc?`: `string`) => `AxFluentFieldType`<`"date"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a date field type for YYYY-MM-DD formatted dates. Values are formatted as date strings without time components (e.g., “2024-01-15”). For datetime values with time, use `f.datetime()` instead. Example `f.date('Date of birth') f.date('Publication date')`
`dateRange()`	(`desc?`: `string`) => `AxFluentFieldType`<`"dateRange"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a date range field type. Values normalize to `{ start: Date; end: Date }`. Prefer interval strings such as `2024-01-15/2024-01-20` or JSON objects with `start` and `end`.
`datetime()`	(`desc?`: `string`) => `AxFluentFieldType`<`"datetime"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a datetime field type for ISO 8601 timestamps. Values are formatted as full ISO 8601 datetime strings (e.g., “2024-01-15T14:30:00Z”). For date-only values, use `f.date()` instead. Example `f.datetime('When the event occurred') f.datetime('Appointment start time')`
`datetimeRange()`	(`desc?`: `string`) => `AxFluentFieldType`<`"datetimeRange"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a datetime range field type. Values normalize to `{ start: Date; end: Date }`. Prefer ISO 8601 interval strings such as `2024-01-15T14:30:00Z/2024-01-15T15:30:00Z` or JSON objects with `start` and `end`.
`email()`	(`desc?`: `string`) => `AxFluentFieldType`<`"string"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates an email field type with email format validation. Shorthand for `f.string().email()`. The AI will be instructed to return a valid email address format. Example `f.email('Contact email address') f.email().optional()`
`file()`	(`desc?`: `string`) => `AxFluentFieldType`<`"file"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a file field type for document inputs. Pass files as base64-encoded data or file references. Only supported as input fields with models that support file processing (PDFs, documents, etc.). Note: Cannot be used in nested `f.object()` fields - only as top-level inputs. Example `f.file('PDF document to summarize') f.file('Resume to parse')`
`image()`	(`desc?`: `string`) => `AxFluentFieldType`<`"image"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates an image field type for multimodal inputs. Pass images as base64-encoded data URLs or URLs to external images. Only supported as input fields with multimodal models (GPT-4V, Claude 3, Gemini, etc.). Note: Cannot be used in nested `f.object()` fields - only as top-level inputs. Example `f.image('Product photo to analyze') f.image('Screenshot of the UI bug') f.image().array('Multiple images to compare')`
`json()`	(`desc?`: `string`) => `AxFluentFieldType`<`"json"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a JSON field type for arbitrary structured data. Use this when you need flexible object output without a predefined schema. For structured data with known fields, prefer `f.object()` for type safety. Example `f.json('Extracted entities as key-value pairs') f.json('Configuration object')`
`number()`	(`desc?`: `string`) => `AxFluentFieldType`<`"number"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a number field type. Numbers can be integers or floats. Use `.min()` and `.max()` to constrain the range. Example `f.number('Age in years') f.number().min(0).max(100) // Constrained range f.number('Rating').min(1).max(5)`
`object()`	<`TFields`>(`fields`: `TFields` & `ValidateNoMediaTypes`<`TFields`>, `desc?`: `string`) => `AxFluentFieldType`<`"object"`, `false`, `undefined`, `false`, `false`, `TFields`, `false`>	Creates a nested object field type with typed properties. Use this when you need structured output with known fields. Each property in the fields object should be created using `f.string()`, `f.number()`, etc. Objects can be nested to create complex hierarchical structures. Restrictions: - Media types (`image`, `audio`, `file`) cannot be used in nested objects - Deep nesting may reduce AI output quality Examples `f.object({ name: f.string('Person name'), age: f.number('Age in years'), isActive: f.boolean() }, 'User profile')` `f.object({ title: f.string(), author: f.object({ name: f.string(), email: f.email().optional() }), tags: f.string().array() })` `f.object({ item: f.string(), quantity: f.number().min(1) }).array('List of order items')`
`string()`	(`desc?`: `string`) => `AxFluentFieldType`<`"string"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a string field type. Strings are the default and most common field type. Use modifiers to add validation constraints. Example `f.string('User question') f.string().min(10).max(1000) // Length constraints f.string().email() // Email format f.string().regex('^[A-Z]', 'Must start with uppercase')`
`url()`	(`desc?`: `string`) => `AxFluentFieldType`<`"url"`, `false`, `undefined`, `false`, `false`, `undefined`, `false`>	Creates a URL field type with URI format validation. The AI will be instructed to return a valid URL. Use for outputs that should be clickable links or API endpoints. Example `f.url('Link to the source') f.url('API endpoint URL') f.url().optional()`

Examples

TypeScript

const sig = f()
  .input('name', f.string('User name'))
  .input('age', f.number('Age in years'))
  .output('greeting', f.string('Personalized greeting'))
  .build();

TypeScript

const sig = f()
  .input('email', f.string().email())
  .input('score', f.number('Score between 0-100').min(0).max(100))
  .input('tags', f.string('Tag').array('List of tags'))
  .output('isValid', f.boolean())
  .build();

TypeScript

const sig = f()
  .input('text', f.string('Text to classify'))
  .output('sentiment', f.class(['positive', 'negative', 'neutral'] as const))
  .output('confidence', f.number().min(0).max(1))
  .build();

TypeScript

const sig = f()
  .input('query', f.string())
  .output('result', f.object({
    title: f.string('Article title'),
    score: f.number('Relevance score'),
    metadata: f.object({
      author: f.string().optional(),
      date: f.date()
    })
  }))
  .build();

TypeScript

const sig = f()
  .input('context', f.string().optional())
  .input('question', f.string())
  .output('reasoning', f.string('Step-by-step thinking').internal())
  .output('answer', f.string())
  .build();