# finterm

Reusable finance research for trading agents

Better trades start with better facts for your agent.

finterm gives your agent a complete, source-backed research packet on any company — in a single call. Each packet distills dozens of web searches and hundreds of pages into clean facts, grounded in live prices from multiple market data sources.

Facts, sources, timestamps and caveats. Not investment advice.

## Install

Install — developer preview (current path; requires repo access):
finterm is not on npm yet, so this local install from a finterm repo checkout is the only working install path today (there is no public repo). The root pnpm install is required: the CLI package resolves its dependencies through the root pnpm workspace, so a fresh checkout fails to build without it.
```bash
cd <repo-root>
pnpm install
cd finterm-cli/packages/finterm-cli
pnpm build
mkdir -p "$HOME/.finterm-local/lib"
npm link "$PWD" --prefix "$HOME/.finterm-local"
export PATH="$HOME/.finterm-local/bin:$PATH"
finterm --help
```

Agents: install finterm with the developer-preview commands above, then run finterm --help and follow the auth and setup instructions. Do not install finterm from npm until the package is publicly released.

Once released: npm install -g finterm. Until then, use the developer preview above — the npm package is not published yet, so the npm command must not be run today.

## Agent Setup

```bash
finterm --help
finterm auth login
finterm auth status
finterm setup
finterm skill
```

Run `finterm --help` first after install. Follow the installed CLI help if it differs from this file.

## Packets

### § 01 - The Company Packet
A complete company data room, before your agent reasons.

The core primitive. Fundamentals, earnings, events, filings and narrative — reconciled from dozens of sources into one packet your agent reads in a single call, instead of rebuilding it every session.

### § 02 - Web Research Quality
We strip the HTML and noise, then keep only the signal.

finterm filters raw markup and low-signal finance SEO, dedupes the same press release across a dozen sites, and labels what survives as primary or secondary sources — so your agent reasons from facts, not clickbait.

### § 03 - The Executive Packet
Predictions and plans, in one place.

What a leader forecast versus what they committed to do — pulled from years of calls, keynotes and interviews, dated, sourced, and tracked against what actually happened.

### § 04 - The Politician Packet
All their disclosed trades — plainly.

The full public purchase history in one clean table for humans, and the same rows as markdown for agents. Source-linked, with filing lag and statutory amount ranges kept honest.

### § 05 - The Supply-Chain Packet
The supply chain as a percentage of revenue and cost.

Who the money comes from, and where it goes — customers as a share of revenue, suppliers as a share of cost — so concentration risk is a number, not a vibe.

## Company Research Demo

Use two explicit bundles for the first company research demo: `ticker_data` and `company_web_research`.

### Bundle Catalog

```bash
finterm bundle catalog
finterm bundle describe ticker_data
finterm bundle describe company_web_research
```

### META Company Research Example

```bash
finterm bundle run ticker_data META --company-name "Meta Platforms"
finterm bundle run company_web_research META --company-name "Meta Platforms" \
  --param q=1 fy=2026 prev_q=4 prev_fy=2025
```

The `--param q=<quarter> fy=<fiscal year> prev_q=<previous quarter> prev_fy=<previous fiscal year>` values are required by the web-research template; adjust them to the fiscal period you are researching.

Record each printed run id. Long web-research runs may queue or continue after an agent disconnects.

### Wait and Resume

```bash
finterm bundle wait <run-id>
finterm runs list
```

Use `finterm bundle wait <run-id>` to resume polling. Use `finterm runs list` to find recent local runs.

### Download and Dataroom

```bash
finterm bundle download <run-id> --room ./datarooms/meta --mode new
finterm bundle download <run-id> --room ./datarooms/meta --mode merge
finterm dataroom files ./datarooms/meta
finterm dataroom search ./datarooms/meta "revenue"
finterm dataroom read ./datarooms/meta <artifact-ref>
finterm dataroom resolve-url ./datarooms/meta <source-url>
```

Use `--mode new` for a fresh local Dataroom. Use `--mode merge` to sync more results into an existing Dataroom; locally modified files are kept, not replaced. Re-running a download on a complete room is a fast no-op.

The `finterm dataroom` verbs work on rooms that contain a `dataroom.yml`. If the downloaded room is plain files, read them directly.

## Support and Limits

- The npm package is not published yet; npm install becomes available only after public release.
- Until npm publish, the developer-preview local install from a repo checkout is the only install path.
- The first demo path uses the explicit ticker_data and company_web_research bundles.
- Queued-run wait (`finterm bundle wait`), run listing (`finterm runs list`), and download (`finterm bundle download`) are implemented CLI commands.
- Finterm output is factual and informational only, not investment advice.

Give your agent a finance brain.

---
finterm — a reusable factual data layer for finance agents. Figures, tickers and people shown are illustrative. Data is factual and informational only; nothing here is investment advice or a recommendation to buy or sell.