export declare enum LogLevel { DEBUG = 0, INFO = 1, WARN = 2, ERROR = 3 } /** * Python `logging` level names as they appear in `record.levelname`, so a * structured record filtered by `level` matches Python output ("WARNING", * not "WARN"). */ export type LogLevelName = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR'; /** Root logger name; every {@link getLogger} name is prefixed with it, as in Python. */ export declare const ROOT_LOGGER_NAME = "praisonaiagents"; /** * One log event, the counterpart of Python's `logging.LogRecord`. Field * comments give the Python attribute each one mirrors. */ export interface LogRecord { /** Logger name (`record.name`). */ name: string; /** Level name (`record.levelname`). */ level: LogLevelName; /** Rendered message (`record.getMessage()`). */ message: string; /** Event time (`record.created`); defaults to now. */ timestamp?: Date; /** Source module name without extension (`record.module`). */ module?: string; /** Calling function name (`record.funcName`). */ function?: string; /** Source line number (`record.lineno`). */ line?: number; /** Attached exception (`record.exc_info`). */ error?: unknown; /** Attached stack text (`record.stack_info`). */ stackInfo?: string; /** Free-form context passed to the `Logger` methods (no Python counterpart). */ context?: unknown; /** Per-logger structured fields (`record.extra_data`, from `get_logger(extra_data=...)`). */ extraData?: Record | null; } /** Anything that can turn a {@link LogRecord} into a line of output (Python `logging.Formatter`). */ export interface LogFormatter { format(record: LogRecord): string; } /** Constructor options for {@link StructuredFormatter}. */ export interface StructuredFormatterOptions { /** * `strftime`-style format for the `timestamp` field (Python * `logging.Formatter(datefmt=...)`). `null` emits ISO 8601 (`toISOString`). */ datefmt?: string | null; } /** * JSON formatter for structured logging in production environments. * * Python parity: `StructuredFormatter` in praisonaiagents/_logging.py. Emits * one JSON object per record with the same field names: `timestamp`, `level`, * `logger`, `message`, `module`, `function`, `line`, plus `exc_info` and * `stack_info` when present, then any `extraData` keys that do not collide * with those standard fields. */ export declare class StructuredFormatter implements LogFormatter { /** Field names that `extraData` may never overwrite (Python `_STANDARD_FIELDS`). */ static readonly STANDARD_FIELDS: ReadonlySet; readonly datefmt: string | null; constructor(options?: StructuredFormatterOptions); /** Python `Formatter.formatTime`. */ formatTime(record: LogRecord, datefmt?: string | null): string; /** Python `Formatter.formatException`: the stack trace text of an error. */ formatException(error: unknown): string; /** Python `Formatter.formatStack`. */ formatStack(stackInfo: string): string; /** Format a record as one line of JSON. Python `StructuredFormatter.format`. */ format(record: LogRecord): string; } export declare class Logger { private static _level?; private static verbose; private static pretty; private static formatter; private static get level(); private static getCircularReplacer; private static formatContext; static setVerbose(verbose: boolean): void; static setPretty(pretty: boolean): void; /** * Install (or with `null`, remove) a formatter. While one is installed, * every record from `Logger` and every {@link PraisonLogger} is rendered by * it instead of the plain/pretty output — the counterpart of Python's * `handler.setFormatter(...)` on the root handler. */ static setFormatter(formatter: LogFormatter | null): void; static getFormatter(): LogFormatter | null; /** * Route one event through the level/verbose gates and then to the * formatter, the pretty logger or the plain console. `name` and * `extraData` come from a named {@link PraisonLogger}. */ static log(level: LogLevel, message: string, context?: any, name?: string, extraData?: Record | null): Promise; private static write; static debug(message: string, context?: any): Promise; static info(message: string, context?: any): Promise; static warn(message: string, context?: any): Promise; static error(message: string, context?: any): Promise; static success(message: string, data?: unknown): Promise; static startSpinner(text: string): Promise; static updateSpinner(text: string): Promise; static stopSpinner(success?: boolean): Promise; static table(headers: string[], data: (string | number)[][]): Promise; static section(title: string, content: string): Promise; } /** * A named logger sharing the static `Logger`'s level, verbosity and * formatter — Python's `logging.Logger` (or `_ExtraDataAdapter` when * `extraData` is set). Obtain one through {@link getLogger}. */ export declare class PraisonLogger { readonly name: string; readonly extraData: Record | null; constructor(name: string, extraData?: Record | null); /** A logger with the same name and additional structured fields (Python `LoggerAdapter`). */ withExtraData(extraData: Record): PraisonLogger; debug(message: string, context?: any): Promise; info(message: string, context?: any): Promise; warn(message: string, context?: any): Promise; /** Python spelling of {@link warn}. */ warning(message: string, context?: any): Promise; error(message: string, context?: any): Promise; } /** * Apply Python `get_logger`'s naming convention: every name lives under * `praisonaiagents.`; `__main__` becomes `praisonaiagents.main`; a * `praisonai`/`praisonai.x` name is re-rooted to `praisonaiagents.x`. */ export declare function normalizeLoggerName(name: string): string; /** Keyword options of {@link getLogger}; Python's keyword-only parameters. */ export interface GetLoggerOptions { /** Extra fields merged into every record from this logger (Python `extra_data`). */ extraData?: Record | null; } /** * Get a logger with consistent naming for PraisonAI modules. * * Python parity: `get_logger(name=None, *, extra_data=None)` in * praisonaiagents/_logging.py. The same name always returns the same instance * (Python's `logging.getLogger` registry); when `extraData` is given a fresh * adapter-style logger bound to that name is returned, as Python wraps the * base logger in `_ExtraDataAdapter`. With no name, the calling file's * basename stands in for Python's `__name__`. * * @example * const logger = getLogger('agent.heartbeat'); // praisonaiagents.agent.heartbeat * const scoped = getLogger('agent', { extraData: { agentId: 'assistant' } }); */ export declare function getLogger(name?: string | null, options?: GetLoggerOptions): PraisonLogger; /** * Configure structured JSON logging for production environments. * * Python parity: `configure_structured_logging()` in praisonaiagents/_logging.py. * Exactly like Python it only acts when `PRAISONAI_STRUCTURED_LOGS=true`; * it then installs a {@link StructuredFormatter} on the `Logger`, which every * named logger shares. Useful for log aggregation (ELK, Splunk, CloudWatch). * * @example * process.env.PRAISONAI_STRUCTURED_LOGS = 'true'; * configureStructuredLogging(); */ export declare function configureStructuredLogging(): void;