Back to Documentation

API Reference

Comprehensive API documentation for FinWorld's seven-layer architecture and core modules.

Architecture Overview

FinWorld follows a seven-layer architecture design, where each layer has clear responsibilities and functional boundaries. All components are registered in the global registry and can be referenced by their type field in configuration files.

1. Configuration Layer

Built on top of mmengine, providing a unified and extensible configuration system based on Python dictionaries.

Registry System

All components are registered under global registries:

  • DATASET - Dataset registries
  • ENVIRONMENT - Environment registries
  • MODEL - Model registries
  • AGENT - Agent registries
  • LOSS - Loss function registries
  • METRIC - Metric registries
  • OPTIMIZER - Optimizer registries
  • SCHEDULER - Scheduler registries
  • TRAINER - Trainer registries
  • TASK - Task registries

GitHub: finworld/registry.py

Configuration Files

Task-specific configuration files organized by functionality:

GitHub: configs/

2. Data Layer

Comprises multiple functional modules for standardized, extensible, and task-oriented data management.

Downloader Module

Unified interface for heterogeneous financial data providers:

GitHub: finworld/downloader/

Processor Module

Configurable preprocessing pipelines for numerical and textual data:

GitHub: finworld/processor/

Dataset Module

Task-specific datasets for machine learning:

GitHub: finworld/data/

Environment Module

Interactive environments for reinforcement learning:

GitHub: finworld/environment/

3. Model Layer

Specialized modules supporting unified definition and management of heterogeneous modeling paradigms.

Embedding Components

Data embedding for financial time series:

  • PatchEmbed - Converts time series data into patch-based embeddings for transformer models
  • DataEmbed - General-purpose data embedding layer for financial time series processing
  • TradingDataEmbed - Specialized embedding for trading data with market-specific features
  • PortfolioDataEmbed - Multi-asset portfolio embedding with cross-asset relationships
  • AbsPosition1DEmbed - Absolute positional encoding for one-dimensional time series data
  • AbsPosition2DEmbed - Absolute positional encoding for two-dimensional data structures
  • SinCosPosition1DEmbed - Sinusoidal positional encoding with sine and cosine functions
  • SinCosPosition2DEmbed - Two-dimensional sinusoidal positional encoding for complex data structures
  • DenseLinearEmbed - Linear embedding for dense input data with dropout support
  • DenseConv1dEmbed - 1D convolutional embedding for sequential data processing
  • SparseEmbed - Sparse embedding for categorical and discrete features
  • TimeSparseEmbed - Time-aware sparse embedding for temporal categorical data
  • TimeDenseEmbed - Time-aware dense embedding for temporal continuous data
  • AggEmbed - Aggregation embedding for multi-scale feature representation
  • AggDataEmbed - Aggregated data embedding for multi-level feature extraction
  • TimePatchEmbed - Time-aware patch embedding for temporal patch-based models
  • TradingPatchEmbed - Trading-specific patch embedding for market data patches
  • PortfolioPatchEmbed - Portfolio-specific patch embedding for multi-asset patches
  • FactorVAEEmbed - Factor VAE embedding for disentangled representation learning

GitHub: finworld/models/embed/

Encoder Components

Encoder architectures for financial data:

  • TransformerEncoder - Standard transformer encoder with self-attention mechanisms for financial data
  • VAELSTMEncoder - Variational autoencoder with LSTM backbone for time series representation learning
  • AutoformerEncoder - Autoformer encoder with decomposition-based attention for long-term forecasting
  • CrossformerEncoder - Crossformer encoder with two-stage attention for multivariate time series
  • EtsformerEncoder - ETSformer encoder with exponential smoothing for trend and seasonal components

GitHub: finworld/models/encoder/

Decoder Components

Decoder architectures for financial predictions:

  • TransformerDecoder - Standard transformer decoder with cross-attention for financial prediction tasks
  • VAELSTMDecoder - Variational autoencoder decoder with LSTM for time series generation and reconstruction
  • AutoformerDecoder - Autoformer decoder with decomposition-based attention for long-term financial forecasting
  • CrossformerDecoder - Crossformer decoder with two-stage attention for multivariate time series prediction
  • EtsformerDecoder - ETSformer decoder with exponential smoothing for trend and seasonal forecasting

GitHub: finworld/models/decoder/

Model Components

Complete model implementations:

  • Model - Base model class with common initialization and weight management for all FinWorld models
  • TransformerVAE - Transformer-based variational autoencoder for financial time series generation and representation
  • VQVAE - Vector Quantized Variational Autoencoder with discrete latent representations for financial data
  • DiT - Diffusion Transformer for financial time series generation with denoising diffusion processes
  • ClipTextEncoder - CLIP-based text encoder for multimodal financial data processing and understanding

GitHub: finworld/models/

4. Training Layer

Modular scaffold for optimizing all method pipelines for financial applications.

Optimizer

First-order optimization methods:

  • Adam - Adam optimizer with adaptive learning rates
  • AdamW - AdamW optimizer with weight decay regularization
  • SGD - Stochastic gradient descent with momentum

GitHub: finworld/optimizer/

Loss Functions

Objective functions for financial tasks:

  • MSELoss - Mean squared error loss for regression tasks
  • MAELoss - Mean absolute error loss for robust regression
  • VAELoss - Variational autoencoder loss for generative modeling
  • VQVAELoss - Vector quantized VAE loss for discrete representations
  • FactorVAELoss - Factor VAE loss for disentangled representations
  • PriceLoss - Price prediction loss for financial forecasting

GitHub: finworld/loss/

Scheduler

Learning rate scheduling strategies:

GitHub: finworld/scheduler/

Trainer

Training orchestration and control:

GitHub: finworld/trainer/

5. Evaluation Layer

Unified, extensible, and highly modular evaluation system for financial AI tasks.

Metrics

Financial-specific evaluation metrics:

  • ARR - Annualized rate of return for financial performance evaluation
  • SR - Sharpe ratio for risk-adjusted return measurement
  • Accuracy - Classification accuracy for trading signal evaluation
  • F1Score - F1 score for balanced precision and recall evaluation
  • MSE - Mean squared error for regression task evaluation
  • MAE - Mean absolute error for robust regression evaluation
  • Precision - Precision metric for classification performance
  • Recall - Recall metric for classification sensitivity
  • AUC - Area under the ROC curve for binary classification
  • RANKIC - Rank information coefficient for factor analysis
  • RANKICIR - Rank information coefficient information ratio
  • MDD - Maximum drawdown for risk assessment
  • CR - Calmar ratio for risk-adjusted performance
  • DD - Drawdown duration for risk analysis
  • SOR - Sortino ratio for downside risk assessment
  • VOL - Volatility metric for risk measurement
  • HitRatio - Hit ratio for trading signal accuracy

GitHub: finworld/metric/

Plot

Advanced visualization tools:

  • PlotProKline - Professional candlestick charts for financial data visualization
  • PlotCurve - Cumulative return curves for performance tracking
  • PlotCompass - Compass plots for multi-dimensional financial metrics
  • PlotStar - Star plots for portfolio performance visualization
  • PlotSunBurst - Sunburst diagrams for hierarchical financial data
  • PlotLLMScore - LLM score visualization for language model evaluation

GitHub: finworld/plot/

6. Task Layer

Systematic definition, abstraction, and encapsulation of financial AI task types.

Task Classes

Core task execution framework:

  • Task - Synchronous task execution with trainer integration
  • AsyncTask - Asynchronous task execution for concurrent processing
  • TaskType - Enum defining supported task types (forecasting, trading, portfolio, etc.)

GitHub: finworld/task/

7. Presentation Layer

Automated and multi-modal dissemination of experimental results.

Output Formats

Multi-modal result presentation:

  • HTML - Web page generation
  • LaTeX - Technical report generation
  • PDF - PDF report generation
  • PNG - Figure generation
  • CSV - Table export
  • JSON - Artifact export

GitHub: finworld/

Other Modules

Additional supporting modules and utilities.

Tools Module

Utility tools and functions:

GitHub: finworld/tools/

Memory Module

Memory management for agents:

  • AgentMemory - Main agent memory class for managing conversation history and steps
  • MemoryStep - Base class for all memory step types with message conversion
  • ActionStep - Memory step for agent actions with tool calls and observations
  • PlanningStep - Memory step for agent planning and strategy formulation
  • TaskStep - Memory step for task initialization and user prompts

GitHub: finworld/memory/

Getting Started

To get started with FinWorld's API, check out our documentation and task examples.