CubeOne (Community Edition)

The Python-Native In-Memory OLAP Engine.

A lightweight, high-performance alternative to IBM TM1, built on Python, Pandas, and FastAPI.

📖 Introduction

CubeOne is an open-source, in-memory multidimensional database (OLAP engine) built for the next generation of Financial Planning & Analysis (FP&A). It delivers a lightweight, programmable, Python-native solution that works seamlessly with Excel, empowering finance teams to move faster without sacrificing control.

Unlike traditional enterprise EPM platforms such as IBM TM1 or Oracle Hyperion, CubeOne is designed for flexibility, transparency, and modern development workflows:

• High-Performance Vectorized Engine
  Powered by Pandas vectorized calculations, CubeOne processes millions of records at exceptional speed.

• Multi-Instance by Design
  A clean separation of application logic and data enables multiple business domains to run independently. Note: The Community Edition is optimized for single-user deployment and rapid prototyping.

• Developer-Friendly Architecture
  Data is stored in open formats like JSON and Parquet, exposed through RESTful APIs for easy integration and automation.

• Open Source, Zero License Cost
  No licensing fees, making CubeOne ideal for agile teams, rapid prototyping, and budget-conscious planning and forecasting initiatives.

CubeOne bridges the gap between Excel familiarity and Python-powered analytics—unlocking a faster, smarter, and more open future for FP&A. 💫

✨ Key Features

• ⚡ In-Memory Calculation Engine Sparse matrix storage built on Pandas Multi-Index, enabling real-time aggregation and consolidation.

• 🧮 Business Rules Engine Supports TM1-style rule syntax (e.g. ['Sales'] = ['Price'] * ['Units']), automatically compiled into vectorized Python code.

• 🔌 Stateless REST API Built with FastAPI, featuring a fully decoupled front-end and back-end architecture.

• 📊 Excel Client Powered by xlwings, providing custom functions (M1_DIM_SET, M1_VIEW_READ，etc.) to manage CubeOne components and read/write data directly from Excel.

• 🛡️ Robust Design Includes built-in self-healing mechanisms, ordered CSV loading, and automatic alias cleanup.

• 🔄 ETL Capabilities Supports server-side bulk CSV loading, column transformations, and flexible control over incremental or full overwrite modes.

🏗️ System Architecture

Architecture Diagram

Classic Three-Tier Architecture

1. Core Layer (core.py) Calculation engine responsible for DataFrame joins, group-by operations, and rule-based calculations.

2. Server Layer (server.py) Resource management layer handling dimension and cube persistence, as well as ETL job scheduling.

3. Interface Layer (api.py) HTTP interface exposing Swagger/OpenAPI documentation.

Application & Data Separation

CubeOne adopts a deployment architecture that separates the Application from the Data.

• App Home (Read-Only): Contains source code (app/, main.py`) and libraries. Shared by all instances.

  • Default Location: C:\CubeOne or /opt/cubeone

• Instance Home (Read/Write): Contains business data (.cub, .dim), configuration (cubeone.ini), and logs.

  • Example: D:\Projects\Finance

⚡ Quick Start (Developer Mode)

1. Clone & Install

git clone https://github.com/smilingsand/CubeOne.git
cd <CubeOne_Image_Path> 
pip install -r requirements.txt

2. Run the Demo

We have prepared a sample "Finance" instance for you.

# Windows 
cd <CubeOne_Image_Path>\samples\SalesPlan
python <CubeOne_Image_Path>\main.py --config cubeone.ini 

# Linux/Mac
cd <CubeOne_Image_Path>/samples/SalesPlan
python3 <CubeOne_Image_Path>/main.py --config cubeone.ini 

3. Access

• Swagger API: Open http://127.0.0.1:8001/docs

• Excel Client: Open client_app/cubeone_excel_sample.xlsm

⚙️ Installation & Deployment

1. Prerequisites

• OS: Windows 10/11/Server or Linux.
• Python: 3.10+.

2. Install Dependencies

Bash

pip install fastapi,numpy,pandas,pydantic,Requests,starlette,uvicorn,xlwings

or

pip install -r requirements.txt

3. Deploy Program Files (App Home)

Copy the source code to your program directory (e.g., C:\CubeOne). Your directory structure should look like this:

Plaintext

C:\CubeOne\
├── main.py                  <-- Production Entry Point
├── app\                     <-- Core Package
│   ├── config.py
│   ├── utils.py
│   ├── rules.py
│   ├── core.py
│   ├── server.py
│   ├── api.py
│   └── cubeone_excel.py
├── requirements.txt
├── client_app\             <-- Excel File Sample
│   └── cubeone_excel_sample.xlsm, *.xlsm
├── samples\                <-- Sample Instances
└── docs\ 

---

⚙️ Instance Configuration (Create New Project)

To run a specific business project (e.g., "Finance_Budget"), follow these steps:

1. Create Instance Directory

Create a folder on your data drive, e.g., D:\Projects\Finance. Inside this folder, create subfolders: Data, Logs, Reports.

2. Create Configuration File (cubeone.ini)

In D:\Projects\Finance, create a file named cubeone.ini with the following content:

Ini, TOML

[Instance]
name = Finance_Budget

[System]
# Listening Address: 0.0.0.0 allows LAN access; 127.0.0.1 limits to local machine only
host = 0.0.0.0
# Port must be unique for each instance (e.g., 8001 for Finance, 8002 for Sales)
port = 8001 

[Storage]
# Path relative to this ini file
data_dir = ./Data
logs_dir = ./Logs

[Security]
auth_enabled = False
default_user = admin

3. Start the Server

Run main.py and point it to your configuration file.

Windows (Batch Script Example): Create Start_Server.bat in your instance folder:

DOS

@echo off
:: ==============================
:: 1. set environment variables
:: ==============================

:: set main program PATH
set APP_HOME=<path of main.py>   

:: set Instance PATH
set CONF_PATH=<path of cubeone.ini>

:: ==============================
:: 2. Start Server
:: ==============================

title CubeOne Server - Loading...
echo Starting CubeOne Instance...
echo Program: %APP_HOME%
echo Config:  %CONF_PATH%
echo ------------------------------

python "%APP_HOME%\main.py" --config "%CONF_PATH%"

pause

Linux:

Bash

python3 /opt/cubeone/main.py --config /var/data/finance/cubeone.ini

4. Verify

Open your browser and visit: http://127.0.0.1:8001/docs. If you see the Swagger UI, the instance is running successfully.

Note: please see file "CubeOne (Phase 2) - Installation and Configuration Manual (EN).docx" for more instructions.

📊 Excel Client Configuration (xlwings)

1. Open Client: Open cubeone_excel_sample.xlsm.

2. Config Sheet: Go to the Config sheet and set Server URL to http://127.0.0.1:8001.

3. xlwings Setup:

   • In the Excel Ribbon, go to xlwings.

   • Set PYTHONPATH to your App Home + app folder (e.g., C:\CubeOne\app).

   • Set UDF Modules to cubeone_excel.

   • Click Import Functions.

🗺️ Editions & Roadmap

CubeOne follows an Open Core strategy. We are committed to keeping the high-performance calculation engine open source forever.

Feature	Community Edition	Commercial / Enterprise
In-Memory Calculation Engine	✅	✅
Stateless REST API	✅	✅
Excel Add-in (xlwings)	✅	✅
Web Management UI	🚧 (Help Wanted!)	🗓️
Multi-User Concurrency & Locking	❌ (Single User)	🗓️
User Authentication & RBAC	❌ (Admin Only)	🗓️
More complex rules support and modern rule parser	❌	🛠️
Advanced Functions, like Data Spreading and Sandbox, etc	❌	🗓️
Audit Logs & Recovery	❌	🗓️
Technical Support	Community	SLA Support

Legend:

• ✅ Ready: Fully implemented and production-ready.
• 🚧 In Development: Active work in progress. Contributions welcome!
• 🛠️ Roadmap Priority: Available first to Commercial Licensees.
• 🗓️ Planned: On the roadmap for future release.

🚀 Upcoming for Community Edition

• Web Management UI: We are launching a community-driven project to build the management console.
• More Connectors: Plugins to load data from SQL, CSV, and APIs.
• Performance Tuning: Continuous optimization of the Pandas-based engine.

💼 Commercial Licensing & Enterprise Support

While the Community Edition allows for powerful single-user analytics, organizations requiring AGPL-exemption, SLA Support, or prioritizing features like Multi-User Concurrency on the roadmap can purchase a Commercial License.

Commercial licensees gain priority influence over the development roadmap.

🤝 Contributing

We welcome contributions! Please read our Contribution Guidelines first to understand the project structure and restricted features.

To maintain the stability of the Community Edition and the viability of the project, please follow these guidelines:

1. Web UI: We have separated the UI into a dedicated repository. Please contribute here: CubeOne-WebUI Repository Link.

2. Core Engine: We gladly accept Bug Fixes, Performance Improvements, and Connectors.

3. Feature Restrictions: Please DO NOT submit PRs related to Multi-user Concurrency, Locking Mechanisms, or Auth Layers. These features are reserved for the Enterprise Edition roadmap. Such PRs will be closed to avoid licensing conflicts.

Click here to view the Web UI Recruitment Plan

📚 Documentation

• CubeOne Function Reference

🎥 Video

• CubeOne Introduction

• CubeOne Hands-on Demo

📄 License & Commercial Usage

CubeOne is open-source software licensed under the GNU Affero General Public License v3.0 (AGPLv3).

1. Free for Open Source & Personal Use 🆓

You are free to download, use, and modify CubeOne for personal projects, academic research, or internal testing. If you distribute your modified version or provide it as a network service (SaaS), you must open-source your code under AGPLv3.

2. Commercial & Proprietary Use 💼

If you wish to use CubeOne in a proprietary (closed-source) commercial product, or if you cannot comply with the open-source requirements of AGPLv3, you must obtain a Commercial License.

Commercial licensing options allow you to:

• Embed CubeOne into your proprietary software.

• Distribute your software without releasing your source code.

• Receive official technical support.

💼 Commercial Inquiries

For commercial licensing, please reach out to me on LinkedIn or email me at: > chris.derong.wang @ outlook [dot] com.