Financial Models as Code

This library is in experimental status and the API is likely to change.

Orcaset is a Python library for building financial models as code. Type annotations catch malformed models at write time, so humans and AI agents can build, modify, and audit large models with confidence.

Build and update with confidence— Strong typing promotes correct models and surfaces relationship dependencies, so you can modify models without breaking them.Flexible integration— Connect to any data source and embed in existing workflows by leveraging Python's ecosystem.** Transparent and deterministic**— No black boxes. Materialize and inspect query-specific traces to audit every calculation.** Efficient construction**— Reusable components and terse definitions mean faster iteration and less context rot for agents.

Install from GitHub with uv

or pip

:

uv add git+https://github.com/orcaset/orcaset-py
pip install git+https://github.com/orcaset/orcaset-py

Requires Python 3.14 or later.

Add the orcaset-py

skill to your coding agent by pasting in the following command:

Install the skill from https://github.com/Orcaset/orcaset-py/tree/main/skill/orcaset-py

Orcaset models are built by defining and combining line item classes. Values are materialized by querying over dates, with caching and circular references handled by the evaluation context.

The snippet below defines a simple model with revenue, expenses, and income, then queries quarterly values through 2026.

from datetime import date
from typing import Iterable

from dateutil.relativedelta import relativedelta

from orcaset import (
    Context,
    Formula,
    Period,
    Span,
    SpanSeries,
    Stmt,
    Total,
    fixed_width_table,
    span,
    split_daily,
    sum_spans,
)

start_date = date(2025, 12, 31)
initial_revenue = 100.0
revenue_growth_rate = 0.05

class Revenue(SpanSeries):
    agg = sum_spans(0.0)

    def spans(self) -> Iterable[Span]:
        value = initial_revenue
        for period in Period.seq(start_date, relativedelta(months=1, day=31)):
            yield Span(period, Formula.pure(value), split_daily)
            value *= 1 + revenue_growth_rate / 12

Expenses = span.scale(Revenue, -0.7, name="Expenses")
Income = span.sum([Revenue, Expenses], agg=sum_spans(0.0), name="Income")

stmt = Stmt(Total(Income, [Revenue, Expenses]))

ctx = Context()
qtrly_periods = Period.list(start_date, relativedelta(months=3, day=31), date(2026, 12, 31))
print(fixed_width_table(stmt.values(ctx, qtrly_periods)))

Note that Revenue

is defined on a monthly basis but queried quarterly. Orcaset automatically aligns, interpolates, and aggregates over partial periods.

See the quickstart example for a step-by-step guide covering cells, series, context, and structured output.

Orcaset is licensed under the Server Side Public License. You can freely use it to build internal models for underwriting, valuation, risk, or other analysis. See LICENSE for details.