Metadata-Version: 2.1
Name: strategic-mandate-parallax
Version: 1.0.0a41
Summary: Python SDK for the Parallax quantitative valuation and Monte Carlo simulation platform by Strategic Mandate
Requires-Python: >=3.10
License: Proprietary - Strategic Mandate GmbH
Author: Strategic Mandate GmbH
Author-email: support@strategicmandate.com
Keywords: quantitative-finance,monte-carlo,stochastic-simulation,valuation,project-finance,risk-management,strategic-mandate,parallax
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Project-URL: Homepage, https://strategicmandate.com
Project-URL: Licensing, https://nice.strategicmandate.com
Requires-Dist: numpy>=1.24
Provides-Extra: quant
Requires-Dist: pandas>=2.0; extra == 'quant'
Requires-Dist: scipy>=1.10; extra == 'quant'
Requires-Dist: scikit-learn>=1.3; extra == 'quant'
Requires-Dist: matplotlib>=3.7; extra == 'quant'
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: scipy>=1.10; extra == 'dev'
Requires-Dist: scikit-learn>=1.3; extra == 'dev'
Requires-Dist: matplotlib>=3.7; extra == 'dev'
Description-Content-Type: text/markdown

# Parallax Python SDK (`strategic-mandate-parallax`)

**Numerical Insight Controls Execution** — Official Python SDK for the **Parallax** quantitative valuation and Monte Carlo simulation platform by **Strategic Mandate GmbH**.

## Installation

```bash
pip install strategic-mandate-parallax
# With full quantitative finance & visualization stack (pandas, SciPy, scikit-learn, Matplotlib):
pip install "strategic-mandate-parallax[quant]"
```

In Python, import the package as **`parallax`**:

```python
import parallax
from parallax import Engine, Model, Config, Simulation, Valuation, Asset, Capex, Revenue
from parallax import viz
```

---

## Architecture & Commercial Licensing (`parallax-license`)

Like commercial solver packages (`gurobipy`, `blpapi`), **`strategic-mandate-parallax` on PyPI is a pure-Python thin SDK (`py3-none-any.whl`)** and **does not bundle the proprietary simulation engine binary**.

- **Without an Engine Runtime / License:** You can freely install `strategic-mandate-parallax` in any environment (CI, cloud notebooks, developer laptops) to construct, inspect, type-check, and serialize models (`parallax.model`) and render institutional exhibits (`parallax.viz`).
- **With a Licensed Engine Runtime (`_parallax_native` + `license.pxl`):** `parallax.Engine()` dynamically loads the native binary runtime from `~/.parallax/runtime/` (or `PARALLAX_RUNTIME_DIR` / your Strategic Mandate installation) and unlocks sub-millisecond in-process Monte Carlo execution with zero-copy IEEE-754 binary memory views into `numpy` and `pandas`.

### Activating Your License & Runtime

```bash
# 1. Inspect current license and native runtime status
parallax-license status

# 2. Install your cryptographic license file (.pxl)
parallax-license install-license ~/Downloads/license.pxl

# 3. Install the native engine runtime binary for your platform
parallax-license install-runtime ~/Downloads/_parallax_native.cpython-314-darwin.so
```

---

## Key Capabilities

1. **Typed Python Component Model (`parallax.model`):** 92 strongly-typed component classes (`Model`, `Config`, `Simulation`, `Valuation`, `Asset`, `Capex`, `Revenue`, `Expense`, `DebtFacility`, `EquityIssuance`, `GlobalVariable`, `DistConfig`, `Scenario`, `Trigger`, `TrpEvent`, etc.) for programmatic and batch model generation.
2. **In-Process Native Engine (`parallax.Engine`):** Executes stochastic simulations in-process with multi-threaded parallel sampling.
3. **Zero-Copy Binary Transfer to NumPy, pandas & scikit-learn:** Reads IEEE-754 `float64` scalar sample vectors (`eng.scalar_array`) and `(n_paths, n_periods)` time-series matrices (`eng.timeseries_matrix`) directly into `numpy.ndarray`, `pandas.DataFrame`, and `scikit-learn` `(X, y)` datasets (`eng.sklearn_dataset`).
4. **Financial Statements & Schedules as Pandas DataFrames (`parallax.statements`):** Extract Income Statement / P&L (`eng.income_statement_df()`, `eng.pnl_df()`), Balance Sheet (`eng.balance_sheet_df()`), Cash Flow Statement (`eng.cash_flow_df()`), 3-Statement Bundles (`eng.financial_statements()`), Debt Schedules (`eng.debt_schedule_df()`), Cash Waterfalls (`eng.cash_waterfall_df()`), Working Capital (`eng.working_capital_df()`), Financial Ratios (`eng.ratios_df()`), and Sanity Checks (`eng.sanity_checks_df()`) — supporting both full deterministic base-case tables (`statistic="base"`) and Monte Carlo quantile/moment or single-path statements (`statistic="p50"`, `"p5"`, `"mean"`, or `path_id=0`).
5. **Model & Catalog Introspection (`parallax.introspection`):** Inspect any project via interactive treeviews (`model.tree()` — Unicode box-drawing in terminals, collapsible Strategic Mandate HTML in Jupyter), settings tables (`model.settings_df()`), global variables (`model.globals_df()`), component inventories (`model.components_df()`, `model.capex_df()`, `model.financing_df()`, `model.operations_df()`), deep component inspection (`model.inspect("Brewery_Loan")`), and live engine catalog DataFrames (`eng.catalog_view()`, `eng.mc_catalog_df()`, `eng.templates_df()`, `eng.distributions_df()`, `eng.processes_df()`, `eng.functions_df()`, `eng.metrics_df()`).
6. **Interactive Help & AI Coding Agent Guide (`parallax.help_system`):** Built-in discovery (`parallax.help()`, `eng.help("gbm")`, `parallax.help(DebtFacility)`, `parallax.help(search="dscr")`) and token-efficient LLM context generation (`parallax.agent_guide(model=m, engine=eng)` / `m.agent_context()`).
7. **Strategic Mandate Corporate Visualization Suite (`parallax.viz`):** High-DPI quantitative exhibits (`plot_fan_manifold`, `plot_npv_distribution`, `plot_scenario_ranges`, `plot_surrogate_attribution`, `plot_dscr_covenant`, `plot_pv_waterfall`) and institutional `pandas` exhibit tables (`sm_exhibit_table`) with inline SVG sparklines and quantile range bars.

---

## Quick Example: Introspection, Financial Statements & Help

```python
import parallax
from parallax import Engine, Model

with Engine() as eng:
    # 1. Load a template and inspect its hierarchical tree & settings
    m = Model.from_dict(eng.template_get("simple_brewery")["model"])
    print(m.tree())                      # Unicode tree in terminal; interactive HTML in Jupyter
    settings_df = m.settings_df()        # Model-level simulation, config, valuation & tax settings
    globals_df  = m.globals_df()         # Stochastic distributions, processes & constants
    loan_spec   = m.inspect("Brewery_Loan")

    # 2. Run Monte Carlo simulation and extract financial statements as DataFrames
    eng.run(m)
    pnl_base = eng.income_statement_df(drop_zero_rows=True)
    pnl_p50  = eng.income_statement_df(statistic="p50")
    bs_base  = eng.balance_sheet_df(drop_zero_rows=True)
    cf_base  = eng.cash_flow_df(drop_zero_rows=True)
    stmts    = eng.financial_statements()  # .pnl, .balance_sheet, .cash_flow

    # 3. Interactive help & AI agent context
    parallax.help("statements")
    parallax.help(search="dscr")
    agent_md = parallax.agent_guide(model=m, engine=eng)
```

---

## License

Copyright © 2024–2026 **Strategic Mandate GmbH**. All rights reserved.  
See [`LICENSE.txt`](LICENSE.txt) for terms. Commercial licensing: [https://nice.strategicmandate.com](https://nice.strategicmandate.com)
