Explicit conventions · Defensible numerics · Source-first engineering · Excel-native delivery · Reviewable evidence
Overview · Status · Target scope · Architecture · Quality model · Installation · Contributing · Security
KPR is a new Excel/VBA library for financial analytics and instrument pricing.
The project is designed for practitioners who need transparent calculations in Excel without surrendering the model contract to an opaque workbook formula or an undocumented convention. Its intended foundation is a set of reusable, source-controlled components that make dates, conventions, cash flows, numerical methods, prices, and analytical results explicit.
KPR aims to sit between two unsatisfactory extremes:
| Extreme | KPR's intended response |
|---|---|
| A one-off workbook with formulas that are difficult to review and reuse | Exported, modular VBA with documented public contracts |
| A black-box pricing stack that is difficult to inspect from Excel | Transparent algorithms, attributable references, and reproducible tests |
Important
KPR is in pre-release development. main contains the implemented v0.0.2
date-layer candidate, but it has no supported installation package or
production release yet. The wider scope described below is a development
direction, not a claim that every capability is already implemented.
| Design goal | Practical value | |
|---|---|---|
| 📐 | Convention-explicit | Day counts, calendars, settlement, compounding, quotation, signs, and curve rules are part of the contract. |
| 🧮 | Numerically defensible | Results are compared with independent references, invariants, boundaries, and stated tolerances. |
| 📊 | Excel-native | The library is intended for worksheet UDFs and VBA callers without hiding the analytical logic. |
| 🔍 | Reviewable source | Exported .bas, .cls, .frm, .frx, and RibbonX files provide a diffable engineering record. |
| 🧱 | API-disciplined | Supported entry points are separated from callbacks, infrastructure, and internal helpers. |
| 🔒 | Caller-safe | Workbook content and global Excel state remain caller-owned unless an API explicitly establishes mutation scope. |
| ⚙️ | Deployment-conscious | Design targets managed Windows environments and both 32-bit and 64-bit Office. |
| 🧾 | Evidence-led | Validation reports what ran, on which environment, against which reference, and what remains unverified. |
KPR is pre-release. The v0.0.1 tag records repository setup only. The
v0.0.2 date-layer contract is frozen and its 22-name calculation surface is
implemented on main; registration, complete generated fixtures and evidence,
UI integration, demo assembly, and exact-candidate certification are still in
progress.
✅ Established present and usable as repository policy
🚧 In progress actively being defined or migrated
🧭 Target planned direction; not yet a supported contract
— Not published no supported functional release artifact or API exists yet
| Area | Status | Boundary |
|---|---|---|
| Repository identity and governance | ✅ | KPR-native README, conduct, contribution, security, and changelog baselines |
| Date-layer contract | ✅ | The normative v0.0.2 behavior and exact 22-name surface are frozen in docs/DATE_LAYER_CONTRACT.md |
| Supported release API | — | The implemented date surface is still an untagged candidate, not a supported functional release |
| KPR analytical source | 🚧 | Gregorian primitives, strict parsing, host/date-system policy, pillar conversion, and scalar/array wrappers are implemented but not release-certified |
| Numerical reference sets | 🧭 | Evidence format and provenance will be defined with each analytical surface |
| Regression harness | 🚧 | Focused scalar, host, pillar, surface, shape, and parity suites exist; complete generated fixtures and release evidence remain open work |
| Installable workbook or add-in | — | No official package is available |
| Tagged release | ✅ | v0.0.1 certifies repository setup only; no functional production release exists |
Warning
Files on main are development material. Do not describe them as a supported
KPR release or use them as the sole basis for a material financial decision.
KPR_DATES_DAYS.basexposes exactly 22KPR_Dates_*functions.- The 21 value-taking functions share one scalar/array-capable surface;
KPR_Dates_HostDateSystem()remains scalar-only. - Text dates accept ISO
YYYY-MM-DDonly, and the supported date window is1900-03-01 .. 9999-12-31. - Multi-cell behavior is claimed only for dynamic-array Excel; no legacy CSE claim is made.
- Focused Windows Excel results for the implemented array surface are recorded on issue #17. They support that issue's closure but do not replace the final exact-source certification owned by issue #29.
See the date-layer contract for behavior and the implementation plan for remaining scope and sequencing.
KPR is intended to grow in layers, with foundational contracts landing before instrument pricing that depends on them.
| Capability | Intended coverage |
|---|---|
| 📅 Date handling | Validated Excel/VBA dates, serial boundaries, and deterministic parsing rules |
| 🏦 Business calendars | Reusable holiday calendars, weekends, and calendar composition |
| ↪️ Date rolling | Unadjusted, following, preceding, modified, and nearest-style conventions where specified |
| ⏱️ Day counts | Explicit accrual conventions with documented boundary behavior |
| 🗓️ Schedules | Coupon/payment schedules, stubs, end-of-month behavior, and adjusted/unadjusted dates |
| Capability | Intended coverage |
|---|---|
| 📈 Rate mathematics | Simple, compounded, continuously compounded, and discount-factor transformations |
| 💰 Time value | Present value, future value, annuity, and cash-flow primitives |
| 📉 Interpolation | Explicit interpolation/extrapolation methods and domains |
| 🧱 Curves | Reviewable curve representations and, later, calibration/bootstrapping components |
| Capability | Intended coverage |
|---|---|
| 🧾 Cash flows | Dated, signed, currency-aware cash-flow structures |
| 🏷️ Money-market products | Deposits and related short-rate instruments |
| 📜 Fixed income | Bond cash flows, accrued interest, clean/dirty price, and yield relationships |
| 🔁 Linear derivatives | FRAs, futures-style analytics, and interest-rate swaps as foundations mature |
| 🧩 Extensions | Additional instruments only when conventions, references, and tests are defensible |
| Capability | Intended coverage |
|---|---|
| 🎯 Sensitivities | Transparent finite-difference or analytical measures with bump conventions |
| 🌡️ Scenarios | Deterministic input transformations and reproducible result comparisons |
| 🔎 Diagnostics | Convergence, domain, convention, and missing-input information |
| 📊 Aggregation | Cash-flow and analytical summaries with explicit units and signs |
This is a directional scope, not a release commitment. Exact functions, signatures, defaults, and sequencing will be documented as they are designed and validated.
Every supported calculation should answer the questions that determine its meaning:
| Contract dimension | Examples |
|---|---|
| 🧾 Instrument | Cash flows, payoff, rights, obligations, and optionality |
| 📅 Dates | Valuation, trade, settlement, fixing, payment, and maturity |
| 💱 Units | Currency, notional, price scale, rate scale, and output units |
| 🗓️ Conventions | Calendar, roll, day count, frequency, stub, and end-of-month rule |
| 📈 Quotation | Price, yield, rate, spread, volatility, discount factor, or probability |
| 🔁 Compounding | Simple, periodic, continuous, or another stated convention |
| ➕ Signs | Long/short, payer/receiver, asset/liability, and cash-flow direction |
| 📉 Curves | Input type, interpolation, extrapolation, compounding, and missing data |
| 🚧 Domain | Valid, invalid, ambiguous, and unsupported inputs |
| Error, structured outcome, non-convergence, and unavailable result | |
| 🎯 Accuracy | Precision, rounding, absolute/relative tolerance, and reference quality |
A formula without its financial conventions is not a reusable pricing contract.
KPR is intended to separate Excel-facing convenience from financial and numerical logic.
flowchart TB
X["Excel UDFs and VBA callers"] --> A["Supported KPR API"]
A --> P["Pricing and analytics engines"]
P --> C["Cash flows and curves"]
C --> F["Dates · conventions · numerics"]
| Layer | Responsibility | Must not silently decide |
|---|---|---|
| 📊 Excel surface | Convert worksheet/VBA inputs and expose supported results | Financial conventions from formatting or locale |
| 🧱 Public API | Validate contracts and provide stable caller-facing behavior | Undocumented defaults or compatibility changes |
| 🧮 Engines | Apply pricing and analytical algorithms | Data ownership or Excel host state |
| 🧾 Cash flows and curves | Represent dated values and market structures | Missing-data or extrapolation policy without a contract |
| 📅 Foundations | Dates, calendars, conventions, solvers, and numerical primitives | Instrument-specific assumptions |
A VBA member being technically Public does not automatically make it supported
consumer API. Excel UDF resolution, RibbonX, Application.Run, callbacks, tests,
or packaging may require public visibility for infrastructure members.
The v0.0.2 candidate calculation API is documented explicitly in the
date-layer contract. Everything outside that
22-name surface is infrastructure or internal implementation unless separately
classified. No candidate API becomes a supported release merely by existing on
main.
The authoritative engineering record is exported, reviewable source. Binary workbooks and add-ins are distribution artifacts, not substitutes for source.
KPR must not infer permission to modify workbook content or global Excel state. Temporary state changes require explicit ownership, bounded scope, cleanup, and failure handling.
An invalid domain, ambiguous convention, non-convergence, or missing input must not produce a plausible-looking result. Failure behavior is part of the public contract.
The implementation under test must not generate its own expected results. Reference values require independent provenance or independently derived invariants and limits.
Compatibility claims must name the Excel, Windows, Office bitness, locale, and date system actually tested. Untested configurations remain unverified.
KPR's intended validation stack is layered:
| Layer | Question answered |
|---|---|
| 🛠️ Compile | Does the complete imported VBA project compile? |
| 🔬 Unit | Does each financial/numerical primitive honor its local contract? |
| 🐛 Regression | Does every corrected defect remain permanently covered? |
| 📚 Reference | Does output match independent values within a justified tolerance? |
| ⚖️ Invariant | Do parity, bounds, monotonicity, symmetry, round trips, and limits hold? |
| Are date, domain, discontinuity, and convergence edges explicit? | |
| 📊 Integration | Do worksheet and VBA entry paths preserve the same financial meaning? |
| 📦 Artifact | Does the packaged workbook/add-in correspond to the tested source? |
A numerical claim should identify:
function and contract
input domain
reference source and precision
absolute / relative tolerance rule
worst observed error and location
Excel / Windows / Office environment
what the evidence does not cover
KPR does not currently publish a certified regression count or numerical accuracy envelope. Those badges and claims will appear only after evidence is generated and committed or attached to a release.
KPR/
├─ .github/
│ ├─ ISSUE_TEMPLATE/ bug and feature intake
│ ├─ scripts/
│ │ └─ labels-sync.mjs label validation and reconciliation
│ ├─ workflows/
│ │ ├─ labels-sync.yml declarative label synchronization
│ │ └─ static-checks.yml hosted repository-integrity gate
│ ├─ labels.json canonical issue-label manifest
│ └─ PULL_REQUEST_TEMPLATE.md
├─ assets/
│ └─ social-preview.png archive-safe README and social-preview source
├─ docs/
│ ├─ DATE_LAYER_CONTRACT.md normative v0.0.2 behavior
│ ├─ IMPLEMENTATION_PLAN.md scope, sequencing, and milestone register
│ └─ VBE_EXPORT.md VBE export/import format
├─ src/
│ └─ modules/
│ ├─ KPR_Core_Err.bas condition and native-error policy
│ ├─ KPR_Core_Parse.bas strict scalar parsing and host classification
│ ├─ KPR_Core_Dates.bas pure Gregorian and pillar calculations
│ ├─ KPR_Core_Array.bas shape, broadcasting, and materialization services
│ └─ KPR_DATES_DAYS.bas 22-name worksheet-facing date facade
├─ test/
│ └─ modules/
│ └─ KPR_REGRESSION_TESTS.bas
├─ tools/
│ └─ check_repo.py static gate and self-test harness
├─ VERSION machine-readable current version
├─ .gitattributes source and line-ending policy
├─ .gitignore local and generated-file exclusions
├─ .editorconfig shared editor baseline
├─ README.md project overview and status
├─ INSTALLATION.md future release installation guidance
├─ CONTRIBUTING.md engineering and evidence standards
├─ CODE_OF_CONDUCT.md community expectations
├─ SECURITY.md security model and disclosure policy
├─ CHANGELOG.md version history from the first release
└─ LICENSE MIT License
The tracked tree is KPR-native. KPR_DATES_DAYS.bas and its four cores are
development source, not a release-certified package. The current regression
module is focused development infrastructure; generated fixtures, final
evidence, demo, registration, and UI files will be added only by their owning
milestone issues.
These are the intended host requirements, pending certification of the first release:
| Requirement | Intended baseline |
|---|---|
| Host | Microsoft Excel desktop |
| Operating system | Windows |
| Office architecture | 32-bit and 64-bit |
| VBA | Macros enabled through an organization-approved trust mechanism |
| Host format | Macro-enabled workbook/add-in where deployment requires VBA |
| Runtime dependencies | No mandatory third-party runtime dependency intended |
| Network | No network access intended for core calculations |
Actual supported versions will be stated only after they have been tested.
No supported KPR installation package exists yet.
Warning
Do not install or redistribute development files from main as an official
KPR workbook or add-in.
The Installation Guide currently provides contributor-only source-import guidance and will be completed when the first installable release candidate defines:
- supported Excel and Windows versions;
- source-import and/or add-in deployment;
- references and macro-trust requirements;
- compilation and post-install validation;
- upgrade and compatibility rules; and
- clean removal.
Future official artifacts will be published only through GitHub Releases.
KPR runs inside Excel with the permissions of the current user. It is not a sandbox or authorization layer.
Read SECURITY.md before deploying macro-enabled code or reporting a vulnerability. Use synthetic examples and disclose suspected vulnerabilities privately.
Contributions are welcome once their financial contract and validation boundary are explicit.
Before contributing, read:
- CONTRIBUTING.md — source, numerical, API, and evidence rules;
- CODE_OF_CONDUCT.md — respectful, evidence-led collaboration;
- SECURITY.md — private disclosure and data-protection boundaries; and
- CHANGELOG.md — release history and unreleased changes.
For material features, pricing models, API changes, dependencies, or architectural work, open an issue before implementation.
The intended sequence is dependency-led:
- complete and certify v0.0.2 date primitives and their Excel integration;
- add calendars, weekend masks, holiday sets, and composition in v0.0.3;
- add business-day arithmetic and roll conventions in v0.0.4;
- establish rate mathematics and numerical primitives;
- add cash-flow and curve representations;
- add instruments only with independent references and contract tests; and
- publish functional releases with reproducible demos, installation guidance, and exact-source validation evidence.
This sequence may change as design work and evidence reveal better boundaries.
KPR follows Semantic Versioning and maintains release notes in Keep a Changelog format.
v0.0.1 is published
as a repository-setup pre-release. It certifies governance, automation, and the
repository baseline; it is not a functional or production-ready release and
does not provide a supported installation package. See
CHANGELOG.md.
KPR is analytical software, not financial, investment, legal, accounting, or regulatory advice. Users remain responsible for independent model validation, market-convention verification, governance, suitability, controls, and review of all outputs used in a material decision or production process.
KPR is licensed under the MIT License.