/**
 * AI Manifest Compiler -- manifest to tool definitions + grammar validation + system prompts.
 *
 * Takes an {@link AIManifest} describing dimensions, slots, actions, and
 * constraints, and compiles it into tool definitions (function calling
 * format), JSON Schema for validation, and system prompts describing
 * available actions.
 *
 * @module
 */
/**
 * Named dimension of UI state (e.g. `theme`, `layout`, `density`).
 *
 * `exclusive: true` means exactly one state is active at a time (a radio
 * group); `exclusive: false` allows multiple concurrent states (a flag set).
 */
export interface AIDimension {
    /** Allowed state names. */
    readonly states: readonly string[];
    /** Currently-active state (must be in `states`). */
    readonly current: string;
    /** Whether only one state can be active at a time. */
    readonly exclusive: boolean;
    /** Human-readable description surfaced to the LLM. */
    readonly description: string;
}
/**
 * Named content slot that accepts a constrained set of content kinds.
 *
 * Slots parameterize a layout — the manifest declares which content kinds
 * (`'image' | 'video' | ...`) each slot will accept.
 */
export interface AISlot {
    /** Content kinds the slot accepts. */
    readonly accepts: readonly string[];
    /** Human-readable description surfaced to the LLM. */
    readonly description: string;
}
/**
 * Named action the LLM may invoke via tool calling.
 *
 * `effects` is a free-form list of effect tags the host uses to route the
 * action's side effects (repaint, persist, etc.).
 */
export interface AIAction {
    /** Parameter schemas keyed by parameter name. */
    readonly params: Record<string, AIParamSchema>;
    /** Effect tags produced when this action runs. */
    readonly effects: readonly string[];
    /** Human-readable description surfaced to the LLM. */
    readonly description: string;
}
/**
 * Parameter schema for a single {@link AIAction} parameter.
 *
 * Mirrors a subset of JSON Schema (`type`, `enum`, `min`, `max`) that is
 * losslessly translatable to both tool-calling and schema validation.
 */
export interface AIParamSchema {
    /** JSON Schema type (`'string'` | `'number'` | `'integer'` | `'boolean'` | `'array'` | `'object'`). */
    readonly type: string;
    /** Permitted enum values. */
    readonly enum?: readonly string[];
    /** Numeric minimum (inclusive). */
    readonly min?: number;
    /** Numeric maximum (inclusive). */
    readonly max?: number;
    /** Whether the parameter must be present; defaults to `false` (JSON Schema convention). */
    readonly required?: boolean;
    /** Human-readable description. */
    readonly description: string;
}
/**
 * Cross-cutting invariant declared alongside the manifest.
 *
 * `condition` is opaque at the type level — hosts evaluate it in their own
 * constraint engine (e.g. a `Plan.Shape` predicate). `message` is what the
 * LLM sees when the constraint is reported as violated.
 */
export interface AIConstraint {
    /** Stable identifier for diagnostics and citation. */
    readonly id: string;
    /** Host-defined condition payload (opaque at this layer). */
    readonly condition: unknown;
    /** Human-readable message for violation reports. */
    readonly message: string;
}
/**
 * Top-level AI manifest describing the UI surface to an LLM.
 *
 * Consumed by {@link AIManifestCompiler.compile} to produce tool
 * definitions, a JSON Schema, and a system prompt in a single pass.
 */
export interface AIManifest {
    /** Manifest schema version. */
    readonly version: string;
    /** State-space dimensions. */
    readonly dimensions: Record<string, AIDimension>;
    /** Content slots. */
    readonly slots: Record<string, AISlot>;
    /** Invocable actions. */
    readonly actions: Record<string, AIAction>;
    /** Cross-cutting invariants. */
    readonly constraints: readonly AIConstraint[];
}
/**
 * Authoring-time manifest input accepted by every {@link AIManifestCompiler}
 * entry point. All fields are optional; omitted fields default to
 * `version: '1.0'`, empty records for `dimensions`/`slots`/`actions`, and
 * `[]` for `constraints`. The normalized {@link AIManifest} (total fields)
 * is what compile results carry.
 */
export interface AIManifestInput {
    /** Manifest schema version; defaults to `'1.0'`. */
    readonly version?: string;
    /** State-space dimensions; defaults to `{}`. */
    readonly dimensions?: Record<string, AIDimension>;
    /** Content slots; defaults to `{}`. */
    readonly slots?: Record<string, AISlot>;
    /** Invocable actions; defaults to `{}`. */
    readonly actions?: Record<string, AIAction>;
    /** Cross-cutting invariants; defaults to `[]`. */
    readonly constraints?: readonly AIConstraint[];
}
/**
 * Tool definition in the function-calling format emitted by
 * {@link AIManifestCompiler.generateToolDefinitions}.
 *
 * Directly consumable by the Anthropic, OpenAI, and Google tool-calling
 * APIs — fields are a superset of their intersecting requirements.
 */
export interface AIToolDefinition {
    /** Action name. */
    readonly name: string;
    /** Action description (becomes the tool description). */
    readonly description: string;
    /** JSON Schema for parameters. */
    readonly parameters: Record<string, unknown>;
    /** JSON Schema for the return shape. */
    readonly returns: Record<string, unknown>;
}
/**
 * Output of {@link AIManifestCompiler.compile}.
 *
 * Bundles the source manifest together with the three derived artifacts
 * (tools, schema, prompt) so consumers can wire all three into an LLM
 * session in a single step.
 */
export interface AIManifestCompileResult {
    /** The source manifest. */
    readonly manifest: AIManifest;
    /** Tool definitions for function calling. */
    readonly toolDefinitions: readonly AIToolDefinition[];
    /** JSON Schema for validating LLM output. */
    readonly jsonSchema: Record<string, unknown>;
    /** System prompt describing dimensions, slots, actions, and constraints. */
    readonly systemPrompt: string;
}
/**
 * Generate tool definitions (function calling format) from an AIManifest's actions.
 *
 * @example
 * ```ts
 * import { AIManifestCompiler } from '@czap/compiler';
 *
 * const tools = AIManifestCompiler.generateToolDefinitions(manifest);
 * // tools[0] => { name: 'setTheme', description: '...', parameters: {...}, returns: {...} }
 * ```
 *
 * @param input - The AI manifest containing action definitions (omitted fields take documented defaults)
 * @returns An array of {@link AIToolDefinition} objects
 */
declare function generateToolDefinitions(input: AIManifestInput): readonly AIToolDefinition[];
/**
 * Generate a system prompt describing all available dimensions, slots,
 * actions, and constraints from the manifest.
 *
 * @example
 * ```ts
 * import { AIManifestCompiler } from '@czap/compiler';
 *
 * const prompt = AIManifestCompiler.generateSystemPrompt(manifest);
 * // Use as the system prompt for an LLM conversation
 * ```
 *
 * @param input - The AI manifest to describe (omitted fields take documented defaults)
 * @returns A markdown-formatted system prompt string
 */
declare function generateSystemPrompt(input: AIManifestInput): string;
/**
 * Structured validation failure for AI-generated output — the teach-by-data
 * shape consumed by LLM re-prompting loops. `message` is the prose form
 * surfaced through the parallel `errors` array.
 */
export interface AIValidationIssue {
    /** Dot path into the output, e.g. 'params.cols' or 'dimensions.layout'. */
    readonly path: string;
    /** What the manifest expects at that path. */
    readonly expected: string;
    /** What the output actually carried. */
    readonly received: string;
    /** Literal next step to repair the output. */
    readonly hint: string;
    /** Prose form — identical to the corresponding `errors` entry. */
    readonly message: string;
}
/**
 * Validate AI-generated output against a manifest's constraints and schema.
 * Returns `valid` plus parallel `errors` (prose) and `issues` (structured
 * `{ path, expected, received, hint, message }`) arrays.
 *
 * @example
 * ```ts
 * import { AIManifestCompiler } from '@czap/compiler';
 *
 * const manifest = {
 *   actions: { setLayout: { params: { cols: { type: 'number', required: true, min: 1, max: 12, description: 'Column count' } }, effects: [], description: 'Set grid layout' } },
 * };
 * const check = AIManifestCompiler.validateAIOutput(
 *   { action: 'setLayout', params: { cols: 3 } },
 *   manifest,
 * );
 * console.log(check.valid); // true
 * ```
 *
 * @param output   - The AI-generated output object to validate
 * @param input - The manifest defining valid actions, dimensions, and slots (omitted fields take documented defaults)
 * @returns An object with `valid` boolean, `errors` array, and structured `issues` array
 */
declare function validateAIOutput(output: unknown, input: AIManifestInput): {
    valid: boolean;
    errors: readonly string[];
    issues: readonly AIValidationIssue[];
};
/**
 * Compile an AI manifest into tool definitions, JSON Schema, and a system prompt.
 *
 * Omitted manifest fields are normalized to documented defaults
 * (`version: '1.0'`, empty `dimensions`/`slots`/`actions`, no `constraints`),
 * so a manifest can declare only the surfaces it actually has.
 *
 * @example
 * ```ts
 * import { AIManifestCompiler } from '@czap/compiler';
 *
 * const manifest = {
 *   actions: {
 *     setTheme: {
 *       params: { theme: { type: 'string', enum: ['light', 'dark'], required: true, description: 'Theme' } },
 *       effects: ['theme-change'], description: 'Set the color theme',
 *     },
 *   },
 * };
 * const result = AIManifestCompiler.compile(manifest);
 * console.log(result.toolDefinitions[0].name); // 'setTheme'
 * console.log(result.systemPrompt); // system prompt describing available actions
 * ```
 *
 * @param input - The AI manifest to compile (omitted fields take documented defaults)
 * @returns An {@link AIManifestCompileResult} with tools, schema, and prompt
 */
declare function compile(input: AIManifestInput): AIManifestCompileResult;
/**
 * AI manifest compiler namespace.
 *
 * Compiles an {@link AIManifest} into tool definitions (function calling format),
 * a JSON Schema for validation, and a system prompt describing available
 * dimensions, slots, actions, and constraints. Also provides validation of
 * AI-generated output against the manifest schema.
 *
 * @example
 * ```ts
 * import { AIManifestCompiler } from '@czap/compiler';
 *
 * const manifest = {
 *   dimensions: { theme: { states: ['light', 'dark'], current: 'light', exclusive: true, description: 'Color theme' } },
 *   slots: { hero: { accepts: ['image', 'video'], description: 'Hero section' } },
 *   actions: { setTheme: { params: { theme: { type: 'string', enum: ['light', 'dark'], required: true, description: 'Theme' } }, effects: ['repaint'], description: 'Switch theme' } },
 * };
 * const compiled = AIManifestCompiler.compile(manifest);
 * const valid = AIManifestCompiler.validateAIOutput(
 *   { action: 'setTheme', params: { theme: 'dark' } },
 *   manifest,
 * );
 * ```
 */
export declare const AIManifestCompiler: {
    readonly compile: typeof compile;
    readonly validateAIOutput: typeof validateAIOutput;
    readonly generateSystemPrompt: typeof generateSystemPrompt;
    readonly generateToolDefinitions: typeof generateToolDefinitions;
};
export {};
//# sourceMappingURL=ai-manifest.d.ts.map