Fintern

Fintern is an open-source Python toolkit for explainable financial analysis. It brings market data, fundamentals, instrument identifiers, and transparent analytics together in one consistent workflow.

Fintern is designed for analysts, researchers, and developers who want financial calculations they can inspect, understand, and extend. Data provenance, joins, and analytical logic remain explicit at every step.

Capabilities

• normalized market data downloads, storage, and retrieval
• normalized financial statements and company profiles
• instrument resolution across financial identifiers
• explicit market and fundamentals alignment
• fiscal-period normalization and trailing-twelve-month fundamentals
• company, return, risk, growth, profitability, and valuation analytics
• historical analysis and explainable red-flag detection
• transparent company scoring with coverage and component-level evidence
• point-in-time peer comparison with ranks and relative statistics
• comparable-company and discounted-cash-flow valuation models
• v1.1 economic-data architecture for revision-aware macro and industry context
• optional peer-relative scoring
• standalone Markdown and HTML company reports
• extensible providers and metrics architecture

The roadmap now focuses on package hardening and broader provider coverage.

HTML reports can embed DCF, performance/drawdown, and peer valuation charts. Install fintern[viz] and pass --with-charts to examples/full_report.py, or supply charts=build_report_charts(...) to CompanyReport. Images are embedded in the HTML; Markdown retains tables. See report documentation.

Canonical Economic Indicators

from fintern import download_indicators

data = download_indicators(
    ["real_gdp", "inflation", "policy_rate"],
    geography="US",
    provider="fred",
    as_of="2025-12-31",
)

Requires fintern[fred] and FRED_API_KEY. Native series_id, provider and vintage metadata are preserved; indicator records the canonical name. The catalog covers US/FRED and verified France DBnomics series. inflation returns the CPI index level; year-over-year change gives inflation. See economics documentation.

DBnomics native downloads are also available with fintern[dbnomics]:

from fintern import download_economic_data

data = download_economic_data(
    ["provider/dataset/series"],  # Replace with a full native DBnomics ID.
    provider="dbnomics",
    vintage="latest",
    start="2020-01-01",
)

DBnomics supports current values only: as_of, first_release, and all are rejected. Publication/vintage dates remain unknown. Two France mappings are verified against real API captures:

data = download_indicators(
    ["inflation", "unemployment"],
    geography="FR",
    provider="dbnomics",
    start="2020-01-01",
)

inflation returns all-items HICP index levels (2015=100); unemployment returns a seasonally adjusted percentage of labour force. Metadata mismatches are rejected; native geography is preserved. See coverage and guarantees.

Native ECB exchange rates are available with fintern[sdmx]:

from fintern import download_sdmx_data

data = download_sdmx_data(
    source="ECB", dataflow="EXR", key="D.USD.EUR.SP00.A",
    start="2025-01-02", end="2025-01-06",
)

Initial scope: ECB/EXR daily and monthly complete native keys, latest values only. as_of and historical vintages are rejected. Native dimensions and scoped attributes persist; publication dates and unspecified geography remain unknown. See SDMX guarantees.

Installation

Install the latest development version directly from source.

Core install

git clone https://github.com/loic-mmt/fintern.git
cd fintern

python3 -m venv .venv
source .venv/bin/activate

python -m pip install -e .

With development tools

python -m pip install -e ".[dev]"

With data provider extras

python -m pip install -e ".[data]"

Available extras:

Extra	Purpose
yahoo	Yahoo Finance market data via yfinance
sec	SEC fundamentals via requests
openfigi	OpenFIGI instrument mapping via requests
fmp	Scaffolded adapter
eodhd	Scaffolded adapter
alpha-vantage	Scaffolded adapter
data	Convenience extra for current v1 data stack
viz	Optional PNG charts embedded in HTML reports
parquet	Parquet load/save via PyArrow
dev	Testing, linting, and packaging tools

Quickstart

Company analysis

from fintern import Company

company = Company(
    ticker="AAPL",
    data=market_data,
    fundamentals=fundamentals,
    as_of="2025-12-31",
)

print(company.total_return())
print(company.profitability().operating_margin())
print(company.score().as_dict())

Legacy price-only use remains supported with Company("AAPL", close_prices).

Complete download-to-report workflow

examples/full_report.py downloads market and fundamental data explicitly, runs scoring, red flags, peer comparison, comparable valuation, DCF scenarios and sensitivity, then writes Markdown and HTML reports.

python -m pip install -e ".[yahoo,sec]"
export FINTERN_SEC_USER_AGENT="Your Name your.email@example.com"

python examples/full_report.py \
  --ticker AAPL \
  --peers MSFT,GOOGL,META \
  --as-of 2025-12-31 \
  --output-dir reports

Economic context is opt-in and requires FRED:

python -m pip install -e ".[yahoo,sec,fred]"
export FRED_API_KEY="..."

python examples/full_report.py \
  --ticker AAPL \
  --peers MSFT,GOOGL,META \
  --as-of 2025-12-31 \
  --with-economics \
  --industry technology

All provider names, dates, peers, DCF assumptions, scenario assumptions, and sensitivity grids remain CLI-configurable. Tests inject fixture data and never call live APIs.

Visual analysis

examples/visual_analysis.py creates three publication-ready charts from deterministic offline data. The fictitious tickers keep the example reproducible and avoid presenting synthetic results as real investment research.

python -m pip install -e ".[viz]"
python examples/visual_analysis.py --output-dir reports/charts

DCF sensitivity

Performance and drawdown

Peer valuation

Market data

from fintern import download_market_data

market = download_market_data(
    tickers=["AAPL", "MSFT"],
    start="2025-01-01",
    end="2025-03-31",
    provider="yahoo",
)

print(market.head())

Fundamentals data

from fintern import download_fundamentals

fundamentals = download_fundamentals(
    tickers="AAPL",
    provider="sec",
)

print(fundamentals["statements"].head())
print(fundamentals["company_profile"].head())

Build a combined dataset explicitly

from fintern import (
    build_company_dataset,
    download_fundamentals,
    download_market_data,
)

market = download_market_data(
    "AAPL",
    start="2025-01-01",
    end="2025-06-30",
    provider="yahoo",
)
fundamentals = download_fundamentals("AAPL", provider="sec")

dataset = build_company_dataset(
    market_data=market,
    fundamentals=fundamentals,
    join="asof",
)

print(dataset.head())

Normalize fiscal periods and build TTM fundamentals

from fintern import (
    build_ttm_fundamentals,
    select_fundamental_periods,
    select_valuation_periods,
)

quarterly = select_fundamental_periods(
    fundamentals,
    frequency="quarterly",
    as_of="2025-06-30",
)
ttm = build_ttm_fundamentals(
    fundamentals,
    as_of="2025-06-30",
)
annual = select_valuation_periods(
    fundamentals,
    basis="annual",
    as_of="2025-06-30",
)

Quarterly selection separates discrete quarters from YTD and annual facts, keeps the latest filing available at as_of, and derives missing discrete quarters when sufficient cumulative facts exist.

Valuation ratios, peer analysis, scoring, and comparable multiples default to valuation_basis="ttm" (or basis="ttm" on valuation classes). Use annual for latest fiscal-year flows. latest preserves provider-native latest-fact behavior only when explicitly requested. Balance-sheet inputs always use latest available filing at as_of; missing TTM data never silently falls back.

Data Providers

Provider roles are intentionally explicit:

• Yahoo Market prices only.
• SEC Fundamentals only.
• OpenFIGI Instrument resolution only.

This separation keeps data provenance clear and lets each source serve the capability it handles best.

Provider Configuration

Depending on the provider, you may need optional dependencies and environment variables.

Common variables:

• FINTERN_OPENFIGI_API_KEY
• FINTERN_OPENFIGI_USER_AGENT
• FINTERN_SEC_USER_AGENT
• FINTERN_FMP_API_KEY
• FINTERN_EODHD_API_KEY
• FINTERN_ALPHA_VANTAGE_API_KEY

If a requested provider cannot be used, Fintern raises a clear error explaining whether the issue is:

• missing dependency
• missing API key / environment variable
• unsupported capability
• no compatible provider available

Storage Model

Fintern supports both in-memory use and save/load workflows.

• market datasets can be saved as single files or partitioned datasets
• fundamentals are stored as a multi-table dataset
• instrument mappings are stored as a flat table

By default, the library keeps:

• market data separate from fundamentals
• fundamentals separate from instrument mapping

If you want a combined analysis table, use build_company_dataset(...) explicitly rather than a naive row-wise concat.

Documentation

• Data Layer Architecture
• Explainable Company Scoring
• Peer Analysis
• Valuation Models
• Company Facade and Reports
• Public Exceptions
• Economics v1.1

Development

Run the test suite:

pytest -p no:cacheprovider

Run linting:

ruff check src tests

Run branch coverage with current 75% minimum:

pytest -p no:cacheprovider --cov=fintern --cov-report=term-missing

Build wheel and source distribution:

python -m build

GitHub Actions runs these checks on Python 3.11, 3.12, and 3.13, then installs the built wheel in a clean environment and verifies public imports plus the py.typed marker.

Some tests are intentionally optional:

• live API tests are opt-in only
• Parquet tests need pyarrow, included in fintern[dev]; runtime users can install fintern[parquet] or use CSV.

Status

Fintern is actively developed around a modular data and analytics architecture. Its public API may evolve as new providers, metrics, and analysis workflows are added.

Disclaimer

Fintern is intended for research and educational purposes. It does not provide investment advice.