modeleon 0.1.0__tar.gz

modeleon-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# AI coding tools — excluded from open-source extraction
+CLAUDE.md
+.claude/
+.cursor/
+.cursorignore
+.cursorules
+.copilot/
+.github/copilot/

modeleon-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: modeleon
+Version: 0.1.0
+Summary: Financial Model Engineering — Python code compiles to live Excel formulas
+License: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'

modeleon-0.1.0/README.md

@@ -0,0 +1,63 @@
+# Modeleon
+
+**Financial Model Engineering — Python code compiles to live Excel formulas.**
+
+Write financial models in Python. Get real, auditable Excel formulas — not dead values.
+
+```python
+from modeleon import Model
+
+with Model("Revenue Forecast") as m:
+    with m.section("Assumptions"):
+        price = m.var("Price per Unit", 50, style="input")
+        volume = m.var("Volume", 1000, style="input")
+        growth = m.var("Growth Rate", 0.10, style="input")
+
+    with m.section("Revenue"):
+        revenue = m.var("Revenue", price * volume, style="total")
+        next_year = m.var("Next Year", revenue * (1 + growth))
+
+m.to_excel("revenue.xlsx")
+```
+
+`revenue.xlsx` contains `=B2*B3`, not `50000`. Every cell is a live formula you can audit, extend, and trust.
+
+## Why
+
+Financial models are the DNA of business decisions. They live in spreadsheets — unversioned, error-prone, disconnected from data. [94% of spreadsheets contain errors](https://link.springer.com/article/10.1007/s11704-023-2384-6).
+
+Modeleon brings software engineering to financial modeling without leaving Excel. See the [manifesto](https://github.com/modeleonai/modeleon/blob/main/manifesto.md).
+
+## Features
+
+- **Python-Excel parity** — every Python expression produces a real Excel formula
+- **Symbolic compilation** — two-pass compiler: layout first, then formulas
+- **Time as a first-class dimension** — monthly/quarterly/annual, actuals/forecast boundary, auto-aggregation
+- **Style presets** — `input`, `total`, `grand_total`, `computed` — automatic Excel formatting
+- **Named and unnamed variables** — free-form cells are real graph nodes with full dependency tracking
+- **Graph-native** — the model is a DAG, enabling traversal, impact analysis, and AI integration
+- **Plugin system** — extensible via entry points
+
+## Install
+
+```bash
+pip install modeleon
+```
+
+## CLI
+
+```bash
+modeleon build model.py -o output.xlsx
+```
+
+## How it works
+
+1. You write a model in Python using the DSL
+2. The DSL builds a hierarchical expression graph (Model -> Section -> Variable)
+3. Pass 1 (layout): assigns Excel coordinates `(sheet, row, col)` from hierarchy
+4. Pass 2 (formulas): emits Excel formulas using those addresses
+5. The Excel writer produces a fully functional `.xlsx` file
+
+## License
+
+MIT

modeleon-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "modeleon"
+version = "0.1.0"
+description = "Financial Model Engineering — Python code compiles to live Excel formulas"
+requires-python = ">=3.12"
+license = {text = "Apache-2.0"}
+dependencies = [
+    "pydantic>=2.0",
+    "openpyxl>=3.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "hypothesis>=6.0",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[project.entry-points."modeleon.plugins"]
+# Pro registers here: pro = "modeleon_pro.plugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/modeleon"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

modeleon-0.1.0/src/modeleon/__init__.py

@@ -0,0 +1,7 @@
+"""Modeleon — Financial Model Engineering. Python code compiles to live Excel formulas."""
+
+__version__ = "0.1.0"
+
+from modeleon.plugins import load_plugins as _load_plugins
+
+_load_plugins()

modeleon-0.1.0/src/modeleon/plugins.py

@@ -0,0 +1,65 @@
+"""Plugin extension registry for modeleon.
+
+Pro and other extensions register capabilities here via Python entry points.
+Users always write `from modeleon import Model` — pro features appear automatically
+when modeleon-pro is installed.
+
+See ADR-006 for the design rationale.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_registry: dict[str, Any] = {
+    # Extra kwargs accepted by Variable (e.g., control=, access=, style=)
+    "variable_kwargs": {},
+    # Additional compiler passes (run after core compilation)
+    "compiler_passes": [],
+    # Additional node validators (run on graph validation)
+    "node_validators": [],
+    # Track which plugins have loaded
+    "_loaded": [],
+}
+
+_plugins_loaded = False
+
+
+def get_registry() -> dict[str, Any]:
+    """Return the plugin registry. Read-only access for inspection and tests."""
+    return _registry
+
+
+def load_plugins() -> None:
+    """Discover and load all installed plugins from the 'modeleon.plugins' entry point group.
+
+    Called once on engine import. Safe to call multiple times (idempotent).
+    """
+    global _plugins_loaded
+    if _plugins_loaded:
+        return
+    _plugins_loaded = True
+
+    eps = importlib.metadata.entry_points(group="modeleon.plugins")
+    for ep in eps:
+        try:
+            plugin_module = ep.load()
+            plugin_module.register(_registry)
+            _registry["_loaded"].append(ep.name)
+            logger.debug("Loaded plugin: %s", ep.name)
+        except Exception:
+            logger.warning("Failed to load plugin: %s", ep.name, exc_info=True)
+
+
+def reset_registry() -> None:
+    """Reset the registry to its initial state. For testing only."""
+    global _plugins_loaded
+    _registry["variable_kwargs"].clear()
+    _registry["compiler_passes"].clear()
+    _registry["node_validators"].clear()
+    _registry["_loaded"].clear()
+    _plugins_loaded = False

modeleon-0.1.0/tests/test_plugins.py

@@ -0,0 +1,32 @@
+from modeleon.plugins import get_registry, load_plugins, reset_registry
+
+
+def test_registry_has_expected_categories():
+    registry = get_registry()
+    assert "variable_kwargs" in registry
+    assert "compiler_passes" in registry
+    assert "node_validators" in registry
+    assert "_loaded" in registry
+
+
+def test_load_plugins_is_idempotent():
+    reset_registry()
+    load_plugins()
+    loaded_first = list(get_registry()["_loaded"])
+    load_plugins()
+    loaded_second = list(get_registry()["_loaded"])
+    assert loaded_first == loaded_second
+
+
+def test_mock_plugin_registers():
+    reset_registry()
+    registry = get_registry()
+
+    def mock_register(reg: dict) -> None:
+        reg["variable_kwargs"]["test_kwarg"] = "test_handler"
+
+    mock_register(registry)
+    assert registry["variable_kwargs"]["test_kwarg"] == "test_handler"
+
+    # Clean up
+    reset_registry()