import { Observation } from '../types/types';
import { Parameter, Tool, ParametersType } from './ToolTypes';

/**
 * @file BaseTool.ts
 * @description This file defines the abstract `BaseTool` class, which serves as a blueprint
 * for tool implementations in the AI assistant system. Each tool has a name, description,
 * parameters, and citation rules. The `BaseTool` class provides a structure for executing actions
 * and retrieving action rules for use within the assistant's workflow.
 */

/**
 * The `BaseTool` class is an abstract class that implements the `Tool` interface.
 * It is generic over a type parameter `P`, which extends `ReadonlyArray<Parameter>`.
 * This means `P` is a readonly array of `Parameter` objects that cannot be modified (immutable).
 */
export abstract class BaseTool<P extends ReadonlyArray<Parameter>> implements Tool<P> {
    // The name of the tool (e.g., "calculate", "searchTool")
    name: string;
    // A description of the tool's functionality
    description: string;
    // An array of parameter definitions for the tool
    parameterRules: P;
    // Guidelines for how to handle citations when using the tool
    citationRules: string;
    // A brief summary of the tool's purpose
    briefSummary: string;

    /**
     * Constructs a new `BaseTool` instance.
     * @param name - The name of the tool.
     * @param description - A detailed description of what the tool does.
     * @param parameterRules - A readonly array of parameter definitions (`ReadonlyArray<Parameter>`).
     * @param citationRules - Rules or guidelines for citations.
     * @param briefSummary - A short summary of the tool.
     */
    constructor(name: string, description: string, parameterRules: P, citationRules: string, briefSummary: string) {
        this.name = name;
        this.description = description;
        this.parameterRules = parameterRules;
        this.citationRules = citationRules;
        this.briefSummary = briefSummary;
    }

    /**
     * The `execute` method is abstract and must be implemented by subclasses.
     * It defines the action the tool performs when executed.
     * @param args - The arguments for the tool's execution, whose types are inferred from `ParametersType<P>`.
     * @returns A promise that resolves to an array of `Observation` objects.
     */
    abstract execute(args: ParametersType<P>): Promise<Observation[]>;

    /**
     * Generates an action rule object that describes the tool's usage.
     * This is useful for dynamically generating documentation or for tools that need to expose their parameters at runtime.
     * @returns An object containing the tool's name, description, and parameter definitions.
     */
    getActionRule(): Record<string, unknown> {
        return {
            tool: this.name,
            description: this.description,
            parameters: this.parameterRules.reduce(
                (acc, param) => {
                    // Build an object for each parameter without the 'name' property, since it's used as the key
                    acc[param.name] = {
                        type: param.type,
                        description: param.description,
                        required: param.required,
                        // Conditionally include 'max_inputs' only if it is defined
                        ...(param.max_inputs !== undefined && { max_inputs: param.max_inputs }),
                    } as Omit<P[number], 'name'>; // Type assertion to exclude the 'name' property
                    return acc;
                },
                {} as Record<string, Omit<P[number], 'name'>> // Initialize the accumulator as an empty object
            ),
        };
    }
}