@axarai/axar/dist/agent/decorators.d.ts

TypeScript-based agent framework for building agentic applications powered by LLMs

import 'reflect-metadata';
import { ZodSchema } from 'zod';
import { InputOutputType, ModelConfig } from './types';
import { SchemaConstructor } from '../schema';
/**
 * `model` decorator to associate a model identifier and configuration with an agent.
 *
 * @param modelIdentifier - The model identifier string. List of model identifiers available at https://axar-ai.gitbook.io/axar/basics/model
 * @param config - Optional configuration for the model
 * @param config.maxTokens - Maximum number of tokens to generate
 * @param config.temperature - Sampling temperature between 0 and 1. Use either temperature or topP, not both.
 * @param config.topP - Nucleus sampling threshold. Sample from tokens whose cumulative probability exceeds topP. Use either temperature or topP, not both.
 * @param config.topK - Only sample from the top K options for each subsequent token. Recommended for advanced use cases only.
 * @param config.presencePenalty - Penalize tokens based on their presence in the prompt and generated text. Value between -2.0 and 2.0.
 * @param config.frequencyPenalty - Penalize tokens based on their frequency in the generated text. Value between -2.0 and 2.0.
 * @param config.maxRetries - Maximum number of retries for failed requests (defaults to 2 in SDK)
 * @param config.maxSteps - Maximum number of steps for tool calling (defaults to 3)
 * @param config.toolChoice - Tool choice mode - 'auto' or 'none'
 * @returns A class decorator function.
 *
 * @example
 * ```typescript
 * // Basic usage
 * @model('openai:gpt-4-mini')
 * class MyAgent extends Agent<string, string> {}
 *
 * // With configuration
 * @model('openai:gpt-4-mini', {
 *   maxTokens: 100,
 *   temperature: 0.7,
 *   maxRetries: 3,
 *   maxSteps: 5,
 *   toolChoice: 'auto'
 * })
 * class MyConfiguredAgent extends Agent<string, string> {}
 *
 * // With advanced sampling parameters
 * @model('openai:gpt-4-mini', {
 *   topP: 0.9,              // nucleus sampling
 *   topK: 50,               // top-k sampling
 *   presencePenalty: 0.6,   // reduce repetition
 *   frequencyPenalty: 0.5   // reduce common tokens
 * })
 * class CreativeAgent extends Agent<string, string> {}
 * ```
 */
export declare function model(modelIdentifier: string, config?: ModelConfig): ClassDecorator;
/**
 * Specifies the output schema for a class.
 *
 * @param type - The output type specification, which can be:
 *   - A Zod schema
 *   - A class decorated with @schema
 *   - A primitive type (String, Number, Boolean)
 *
 * @example
 * ```typescript
 * // Using primitive
 * @output(String)
 * class StringAgent extends Agent<string, string> {}
 *
 * // Using schema-decorated class
 * @output(UserProfile)
 * class UserAgent extends Agent<string, UserProfile> {}
 *
 * // Using Zod schema directly
 * @output(z.boolean())
 * class BooleanAgent extends Agent<string, boolean> {}
 * ```
 */
export declare const output: (type: InputOutputType) => ClassDecorator;
/**
 * Specifies the input schema for a class.
 *
 * @param type - The input type specification, which can be:
 *   - A Zod schema
 *   - A class decorated with @schema
 *   - A primitive type (String, Number, Boolean)
 *
 * @example
 * ```typescript
 * // Using primitive
 * @input(Boolean)
 * class BooleanAgent extends Agent<boolean, string> {}
 *
 * // Using schema-decorated class
 * @input(UserProfile)
 * class UserAgent extends Agent<UserProfile, string> {}
 *
 * // Using Zod schema directly
 * @input(z.boolean())
 * class BooleanAgent extends Agent<boolean, string> {}
 * ```
 */
export declare const input: (type: InputOutputType) => ClassDecorator;
/**
 * Class-level `systemPrompt` decorator.
 *
 * Use this decorator to add a static system prompt to the entire class.
 * The provided system prompt will be prepended to the list of system prompts for the class.
 *
 * Usage:
 * ```typescript
 * @systemPrompt("Static system prompt.")
 * class ExampleClass {
 *   // Class implementation
 * }
 * ```
 *
 * @param prompt - A static system prompt string to associate with the class.
 * @returns A class decorator function.
 */
export declare function systemPrompt(prompt: string): ClassDecorator;
/**
 * Method-level `systemPrompt` decorator.
 *
 * Use this decorator on methods to dynamically provide a system prompt.
 * The method must return a string or a Promise resolving to a string, which
 * will be added to the list of system prompts for the class.
 *
 * Usage:
 * ```typescript
 * class ExampleClass {
 *   @systemPrompt
 *   async dynamicPromptMethod(): Promise<string> {
 *     return "Dynamic system prompt from the method.";
 *   }
 * }
 * ```
 *
 * @returns A method decorator function.
 * @throws An error if applied to a property or a method that does not return a string.
 */
export declare function systemPrompt(): MethodDecorator;
/**
 * `@tool` decorator to mark a method as a tool with a description and schema.
 * Supports explicit ZodSchema, class-based schema derivation, and primitive types.
 *
 * Usage with ZodSchema:
 * @tool("Description", z.object({ ... }))
 *
 * Usage with class-based schema:
 * @tool("Description")
 * async method(params: ClassBasedParams): Promise<ReturnType> { ... }
 *
 * Usage with primitive types (String, Number, Boolean):
 * @tool("Description")
 * async method(query: string): Promise<string> { ... }
 *
 * When using primitive types, the parameter is automatically wrapped in an object
 * with a 'value' property for the LLM, and unwrapped when calling your method.
 *
 * @param description - Description of the tool's functionality.
 * @param schemaOrClass - Optional Zod schema or class constructor.
 * @returns A method decorator function.
 */
export declare function tool(description: string, schemaOrClass?: ZodSchema<any> | SchemaConstructor): MethodDecorator;