Guides
Conventions, workflows and deep dives, generated from the guides in the repository.
Every guide below is the same Markdown file that lives in the repository's docs/guides folder, so
the docs and the source never drift. Code in these guides is executed in CI.
Conventions
Assumptions and ConventionsTotalFinance does not hide finance conventions. Pro APIs return a Computed<T envelope with value, assumptions, and diagnostics; facade APIs return plain values but expose the same envelope through .explain().Results & the .explain() envelopeEvery runtime operation in TotalFinance is exactly one of four roles, and each role has ONE result grammar (alignment spec Law 2 — settled by both PR-303 reviews):Errors and DiagnosticsTotalFinance separates programmer/input failures from quantitative failures.Levels: raw, facade, analysis, artifact, batch, workflowTotalFinance is one library at six levels, and no level is the only route. The same instrument — a three-month call struck at 105 on a 100 spot, 20% volatility, 4% rate — is priced below at every level so the reader s…Imports and bundlesUse named imports from @insiderfinance/totalfinance/<domain as the portable browser default. The main package includes every domain and feature subpath with no runtime dependencies; only @insiderfinance/totalfinance-m…Adopt TotalFinance without guessing why the numbers changedKeep the old result, the new result, and their actual assumptions together. A close price is not proof that two calculations used the same dividend treatment, expiry instant, day count, contract multiplier, price sour…
Options & strategies
Strategy catalogue (@insiderfinance/totalfinance/strategy)The strategy package builds an option position from legs and computes the full profit-calculator surface: expiration payoff, breakevens, max profit/loss, mark-to-market value + Greeks, probability of profit / expected…Compute only what you need: selective Greeks and exposureA dashboard that charts gamma exposure needs gamma. It does not need option prices, theta or rho, and it does not need them 7,800 times on every refresh. TotalFinance lets every Black–Scholes and exposure call say wha…Convert futures/index levels to ETF levelsStart with a named helper when your pair is listed below. Supply the level to translate and comparable reference prices for both instruments; the helper supplies the method and unit labels. These examples use illustra…
Technical analysis
TotalFinance indicator registryAuto-generated from @insiderfinance/totalfinance/technical-analysis — 335 registered indicators.TotalFinance indicator warmup / lookahead / displacementWarmup is the number of leading bars before the first real value, measured at the canonical parameters shown (via indicator.explain(...).diagnostics.warmup). 335 indicators.TotalFinance TA — the live tier (charting workflows)The technical-analysis package (@insiderfinance/totalfinance/technical-analysis) is built for live, charting-product use, not just end-of-day batch runs. Three pieces make that work: forming-bar peek(), multi-timefram…Saving and restoring a streaming indicatorEvery indicator in @insiderfinance/totalfinance/technical-analysis has a streaming form, and every streaming form is serializable. You feed it bars, save it, load it a week later, and keep feeding it — the output is i…TotalFinance indicator compatibility matrixCross-reference of TotalFinance canonical names against TA-Lib, pandas-ta and TradingView. Any name below resolves via resolveIndicator (case-insensitive). 225 of 335 registered indicators are mapped.
Portfolios & research
End to end: fundamentals → valuation → screen → portfolio → backtest → performanceOne journey across six packages, on committed numbers, with no provider, network, credential, clock, database, MCP server, or UI. Every step's output feeds the next through public types only, and every step is reconci…BacktestingTotalFinance ships three simulation engines and one accounting law. Every engine emits the portfolio ledger's events for what it did, and the equity it reports is the ledger's net asset value — a result that cannot re…Calculate sector performanceUse sectorPerformance when you already have comparable returns for each security. Use sectorPerformanceSnapshot when you need to select historical closes and classifications under explicit information cutoffs. Both ar…Compare reported holdingscompareDisclosedHoldings compares two supplied disclosure snapshots. It reports what changed in those disclosures; a quantity difference does not prove a purchase or sale. The library does not retrieve filings, select…Compare reported holding partitionsUse compareDisclosedHoldingPartitions to compare common-stock disclosure lines while keeping their investment-discretion categories and report-local manager references separate. You supply the selected reports and aut…
Interfaces & trading
Command line@insiderfinance/totalfinance ships the totalfinance binary (embedded API at /cli): the local, machine-first front door to the same operation registry every transport adapts (@insiderfinance/totalfinance/workflows). It…Local HTTP server@insiderfinance/totalfinance ships totalfinance-http (embedded API at /http): a loopback, read-only-by-default HTTP server over the same operation registry every transport adapts (@insiderfinance/totalfinance/workflow…MCP Server@insiderfinance/totalfinance-mcp exposes TotalFinance computations to AI agents through the Model Context Protocol. The server is read-only by default and wraps the same public TotalFinance APIs used by application code.The safe trade lifecycleTotalFinance gives an agent — coded, learned, or an LLM — one lifecycle through which a decision may become an order, and no other: observe → analyze → propose → preflight → authorize → execute → reconcile. Every stag…The trading-agent environmentTotalFinance ships a deterministic environment in which coded policies, learned policies, and LLM agents are developed and evaluated without broker risk. It is portfolioBacktest's own per-instant loop driven from outs…
Project
Getting StartedTotalFinance is an unpublished preview. Until npm publication, use a source checkout; the install commands below describe the planned published experience, not a completed registry installation.Stability tiersTotalFinance 0.1.0 is pre-1.0 software, not a 1.0 stability guarantee. The main toolkit and optional MCP server are the two public packages; the 25 source workspaces remain private. The main package includes preview w…Bundle size reportTotalFinance treats bundle size as a public contract (spec §21.5). Two different measurements below answer different questions. Both are generated from the same fixture/budget records CI enforces. Sizes use 1024 bytes…Security policyTotalFinance computes from the data you pass in. Compute entry points open no network connection and hold no provider key. The optional HTTP server binds to loopback by default; MCP uses stdio. Transports are read-onl…