Metadata-Version: 2.4
Name: finance-skills
Version: 0.14.3
Summary: AI agent financial skill: provenance-aware fundamentals, deterministic screens, explicit-assumption DCF helpers, and fail-closed data gaps.
Author: Bryan
License-Expression: MIT
Project-URL: Homepage, https://github.com/notEhEnG/finance-skills
Project-URL: Repository, https://github.com/notEhEnG/finance-skills
Keywords: finance,stocks,equity-research,valuation,dcf,rule-of-40,fundamentals,yfinance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yfinance>=0.2
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# finance-skills

[![CI](https://github.com/notEhEnG/finance-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/notEhEnG/finance-skills/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/finance-skills)](https://pypi.org/project/finance-skills/)
[![Python](https://img.shields.io/pypi/pyversions/finance-skills)](https://pypi.org/project/finance-skills/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

Auditable public-company research for AI coding agents. One skill, 10 focused
workflows, 29 deterministic detector rules, and a fail-closed financial evidence
engine.

> **Quick start:** install the skill, install its live-data dependency, then run
> `/finance screen NVDA` (or `$finance screen NVDA` in Codex).

```bash
curl -fsSL https://raw.githubusercontent.com/notEhEnG/finance-skills/v0.14.3/install.sh | bash -s -- claude
python -m pip install "yfinance>=0.2"
```

The engine computes and labels the numbers. Your agent interprets the evidence.
Neither is allowed to silently do the other's job.

## Why finance-skills?

Company-analysis agents tend to fail in two ways: they invent plausible numbers,
or they return a data dump without an argument. finance-skills separates those
jobs and tests the boundary.

- **Deterministic fact layer.** Revenue growth, margins, cash conversion, Rule of
  40, net debt, and valuation multiples come from Python—not model arithmetic.
- **Fail-closed evidence.** Missing debt is not zero. Period and currency
  mismatches block affected calculations. Disabled analyses stay visible.
- **Analyst layer with a point of view.** The agent must weigh conflicting
  evidence, state the assumption doing the most work, and explain what would
  change the conclusion.
- **Auditable provenance.** Material values preserve company, period, currency,
  source, confidence, data mode, formula, and evidence paths.
- **Read-only boundary.** No brokerage integrations, trade execution, position
  sizing, guaranteed returns, or personalized buy/sell instructions.

## See it in action

Claude Code answering “Is NVDA overvalued?” with live data:

![finance-skills agent demo](docs/demo-agent.gif)

[Watch the full-quality video](docs/demo-agent.mp4) or the
[engine-only terminal demo](docs/demo.gif).

## What's included

### The skill: `finance`

All research flows use one skill and one evidence contract:

| Command | What it does |
|---|---|
| `/finance init` | Create non-sensitive project research context |
| `/finance screen <ticker>` | Fast, evidence-grounded company assessment |
| `/finance underwrite <ticker>` | Full conditional thesis with specialist perspectives |
| `/finance audit <ticker>` | Accounting-quality, provenance, and detector review |
| `/finance compare <tickers>` | Period- and currency-compatible peer comparison |
| `/finance challenge <ticker>` | Red-team the current thesis and its core assumption |
| `/finance stress <ticker>` | Explicit operating and valuation scenarios |
| `/finance track <ticker>` | Save an immutable research snapshot and watchpoints |
| `/finance refresh <ticker>` | Compare current evidence with saved research |
| `/finance explain <topic>` | Explain a financial concept without company advice |

Use `$finance ...` in Codex. A ticker by itself, or a generic “analyze” request,
routes to `screen`.

### Usage examples

```text
/finance screen NVDA
/finance underwrite CRWV
/finance audit PLTR
/finance compare AMD NVDA
/finance stress NBIS
/finance explain free cash flow
```

Ask thesis questions naturally. “Is CRWV a buy?” becomes a conditional screen,
not a recommendation: what the evidence supports, what could break the thesis,
and which metrics decide the next update.

### Deterministic runtime

The default install contains the focused `SKILL.md`, workflow references,
specialist prompts, Codex metadata, and the 14-module runtime needed by the
current `/finance` workflows. Repository media, development tooling, and legacy
policy documents are not copied into the runtime skill.

## Installation

### Agent skill (recommended)

Run the installer from the project where you want the skill:

```bash
# Choose: claude | codex | cursor | gemini | antigravity | all
curl -fsSL https://raw.githubusercontent.com/notEhEnG/finance-skills/v0.14.3/install.sh | bash -s -- codex

# Required only for live market-data retrieval
python -m pip install "yfinance>=0.2"
```

The installer is version-pinned, copies an allowlisted payload, and refuses to
overwrite a non-empty skill directory. Add `--legacy-alias` only if you still
need the older `/finance-skills` namespace.

| Runtime | Default project path | Invocation |
|---|---|---|
| Claude Code | `.claude/skills/finance/` | `/finance ...` |
| Codex | `.codex/skills/finance/` or `CODEX_SKILLS_DIR` | `$finance ...` |
| Cursor | `.cursor/skills/finance/` | `/finance ...` |
| Gemini CLI | `.gemini/skills/finance/` | `/finance ...` |
| Antigravity | `.antigravity/skills/finance/` | `/finance ...` |

### Standalone Python CLI

```bash
python -m pip install finance-skills==0.14.3
finance screen --ticker NVDA --format json
finance compare --tickers AMD NVDA --format json
finance explain --topic "free cash flow" --format json
```

Use `--fixture` for explicit offline samples. Fixture output is always labelled
as sample data and never substitutes for a failed live request.

## How it works

```text
User request
    │
    ▼
finance skill ── route to exactly one workflow reference
    │
    ▼
workflow_cli.py ── provider orchestration + normalization
    │
    ▼
evidence report ── observations + formulas + 29 detector results
    │
    ▼
agent synthesis ── conclusion + tension + limitations + what to watch
```

The engine owns calculation and provenance. The agent owns interpretation. A
number presented as finance-skills output must exist in the current report;
external filing facts must be separately sourced and never blended into engine
metrics.

The canonical skill router is [`skill/SKILL.src.md`](skill/SKILL.src.md).
Focused workflows live in [`skill/reference/`](skill/reference/). The evidence
and state contracts are documented in
[`docs/redesign-contract.md`](docs/redesign-contract.md).

## Evidence and safety contract

| Allowed | Blocked |
|---|---|
| Report observations and engine calculations | Numbers recalled or inferred by the model |
| Explicit user assumptions, clearly labelled | Silent estimates or repaired missing values |
| Separately attributed primary-filing facts | External values mixed into engine calculations |
| Conditional valuation language with a stated basis | Unconditional “cheap”, “expensive”, buy, sell, or hold |
| Visible fixture, cache, and partial-data limits | Presenting sample or stale data as live |

Automatic company DCF remains disabled unless every required assumption is
explicit. Educational output is not investment advice.

## Data sources and limits

- **Market data:** yfinance, with provider state and retrieval metadata exposed.
- **Filings:** optional SEC Company Facts reconciliation when
  `FINANCE_SEC_USER_AGENT` contains a compliant contact string.
- **Company IR:** explicit project-local observations; never scraped or inferred
  silently.
- **Estimates:** opt-in and kept separate from reported historical evidence.
- **Fixtures:** deterministic CRWV/NBIS samples for demos and offline tests.

Market-data providers can be delayed, incomplete, or definitionally inconsistent.
Verify material revenue, cash flow, debt, cash, shares, and capex claims against
the latest 10-K or 10-Q.

## Persistent research

`/finance init` creates `RESEARCH.md` and `.finance/config.json` without
overwriting existing files. `track` creates immutable company snapshots.
`refresh` produces a deterministic diff and a reviewable thesis-update proposal
instead of silently rewriting prior research.

Only `init`, `track`, and `refresh` write project state. State paths are confined
to the project and use exclusive or append-only writes.

## Evaluation

The public checker evaluates three layers:

| Tier | Examples of what it catches |
|---|---|
| Safe | Unrecognized numbers, recommendation language, hidden disabled analyses |
| Useful | Raw JSON dumps, caveat walls, answers with no analytical substance |
| Synthesized | Draft copying, missing thesis structure, ticker-swappable prose |

See [`docs/eval.md`](docs/eval.md) for the protocol and limitations. It checks
contract adherence, not investment accuracy.

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest tests -q --cov=scripts
ruff check scripts tests
mypy scripts
```

- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
- Security: [`SECURITY.md`](SECURITY.md)
- Releases: [`CHANGELOG.md`](CHANGELOG.md)
- Engine-report schema: [`docs/engine-report.schema.json`](docs/engine-report.schema.json)

## License

[MIT](LICENSE) · Read-only research · Not investment advice
