Publish FinIR-Intent 0.1.0 (deterministic structured-output baseline)

README.md

@@ -1,3 +1,241 @@
 ---
 license: apache-2.0
+language: en
+tags:
+  - finance
+  - structured-generation
+  - rule-based
+  - finir
 ---
+
+# Model Card: FinIR-Intent (baseline v0.1.0)
+
+**This is a deterministic structured-output baseline, not a trained language model.**
+It maps a natural-language financial instruction to the canonical **FinIR Intent
+Contract** (a versioned JSON envelope) using a fixed, fully offline rule set. There
+are no neural weights in this repository.
+
+## What FinIR is
+
+[FinIR](https://github.com/Olyxee/finir) is a financial intermediate representation
+and incremental execution runtime for AI systems: a finance-typed computation graph
+that is validated, compiled, and evaluated with dependency-aware incremental reuse.
+It is published on PyPI (`pip install finir`, runtime `0.1.0`).
+
+## What FinIR-Intent is
+
+FinIR-Intent is the natural-language layer:
+
+```
+natural-language financial request  ->  FinIR-Intent  ->  canonical FinIR Intent Contract (v1.0)
+```
+
+It performs **no financial computation**. Interpretation and execution are strictly
+separated: FinIR-Intent only produces the envelope; the FinIR runtime validates and
+executes it (`finir.intent.execute_intent` / `FinancialModel.apply_intent`).
+
+## The problem it solves
+
+Letting an AI system "just compute" a financial what-if invites silently invented
+numbers and unit/currency errors. FinIR-Intent constrains the language model's job
+to emitting a **typed, validated intent**; the runtime is the single authority on
+whether that intent is executable and what it computes. Vague language becomes an
+explicit `ambiguous` status instead of a fabricated percentage.
+
+## What it is / is not
+
+- **Is**: a small, dependency-free, offline pattern-matching compiler
+  (`src/finir_intent/baseline.py`) — no network, no external LLM/API calls, fully
+  reproducible. It implements the same `finir.intent.IntentCompiler` seam a future
+  LLM-backed compiler would, so it is a drop-in baseline to measure against.
+- **Is not**: a trained/fine-tuned Transformer. Per the workstream brief, "the first
+  milestone is not model training… only after the baseline is measured should we
+  decide whether fine-tuning a small open model provides a meaningful improvement."
+  This baseline exists to make that measurement possible.
+
+## Hugging Face artifact type
+
+Because v0.1.0 ships **code, not weights**, the natural representation is a
+**model repository that contains the baseline package plus this card** — a
+code/inference repo, not a weight checkpoint. The companion benchmark ships as a
+**Datasets** repo, and a **Space** demonstrates the end-to-end flow against the real
+runtime. The page makes explicit that this is a baseline compiler, not neural
+weights. (See `../release/huggingface/` for the export layout.)
+
+## Schema / runtime compatibility
+
+- **FinIR Intent schema version:** `1.0`
+- **Compatible FinIR runtime:** `>=0.1.0,<0.2.0` (verified against the public PyPI
+  `finir==0.1.0`)
+- **FinIR-Intent baseline version:** `0.1.0`
+- The canonical contract is owned by the core `finir` package
+  (`finir.intent.json_schema()`, `schemas/finir-intent-v1.schema.json`). This
+  package **consumes** it and never redefines it.
+
+## Supported operations
+
+| operation | meaning |
+|---|---|
+| `relative_change` | `new = current × (1 + value)` (dimensionless decimal; `-0.08` = −8%) |
+| `set` | `new = value` (with optional `unit` / `currency`) |
+| `absolute_change` | `new = current + value` (with optional `unit` / `currency`) |
+| `range` | sweep `target` over `[min, max]` in `steps` (sole op) |
+| `scenarios` | named scenarios, each a simultaneous operation set |
+
+## Supported targets
+
+Raw model-input node names (no canonical ontology; alias resolution happens in this
+package only, never in the contract): `revenue`, `cogs`, `opex`, `payment_terms`,
+`accounts_payable`, `inventory`, `capex`, `debt`, `interest_rate`, `cash`, `price`,
+`volume`.
+
+## Ambiguity / unsupported / invalid behavior
+
+- **Ambiguous** — a target with no parseable quantity, or vague language → `status:
+  "ambiguous"`, empty operations. **No number is ever invented.** Conflicting
+  operations on one target (e.g. "increase revenue by 5% and also cut revenue by
+  10%") also map to `ambiguous` rather than silently picking one.
+- **Unsupported** — clearly out-of-domain (acquisitions, mergers, hiring/layoffs,
+  IPOs/going public, litigation, buybacks, bankruptcy) → `status: "unsupported"`.
+- **Invalid (semantic)** — a structurally valid but semantically wrong instruction
+  (a currency the target does not use, a `days` unit on a money target) is
+  **transcribed faithfully, never "corrected"**; the FinIR runtime rejects it at
+  execution. This package performs no semantic check itself (no duplicated execution
+  logic).
+
+## Evaluation methodology
+
+Reproduce (deterministic; no network, no LLM):
+
+```bash
+pip install finir==0.1.0
+cd finir_intent
+pip install -e ".[dev]"        # or: PYTHONPATH=src, plus jsonschema
+python eval/evaluate.py        # writes eval/results/latest.json
+```
+
+`eval/evaluate.py` runs the baseline over every
+`intentbench/examples/intentbench_v1.jsonl` example, validates each prediction
+against `finir.intent.json_schema()` (the canonical schema), scores it against the
+paired **ground-truth** expected intent, and — for every executable prediction —
+actually executes it against a small reference `FinancialModel`
+(`src/finir_intent/reference_model.py`) via the real `finir.intent.execute_intent`.
+Every number below is computed from that run; none is hand-typed.
+
+### Benchmark split (anti-leakage)
+
+FinIR-IntentBench is split into **core** (in-distribution phrasing the rule set is
+built to support) and a held-out **stress** subset (paraphrases the baseline was
+**not** tuned against — unlisted verbs, fractions, magnitude suffixes, idioms). The
+baseline was deliberately **not** modified to pass stress cases, so the stress
+numbers are an honest measure of the rule set's real coverage gap, not a tuned
+score.
+
+## Evaluation results
+
+Produced by an actual run of `python eval/evaluate.py` on
+`intentbench_v1.jsonl` (183 examples: 143 core, 40 stress). Full per-example output,
+including every prediction and its execution outcome against the real runtime, is in
+`eval/results/latest.json`. **Re-run the command above to reproduce** if the code has
+changed.
+
+| metric | overall (n=183) | core (n=143) | stress (n=40) |
+|---|---|---|---|
+| schema validity | 1.0000 | 1.0000 | 1.0000 |
+| status accuracy | 0.9344 | 1.0000 | 0.7000 |
+| operation accuracy | 0.9515 | 1.0000 | 0.7500 |
+| target accuracy | 0.9515 | 1.0000 | 0.7500 |
+| value accuracy | 0.9363 | 1.0000 | 0.5833 |
+| unit accuracy | 1.0000 | 1.0000 | 1.0000 |
+| currency accuracy | 1.0000 | 1.0000 | 1.0000 |
+| ambiguity precision | 0.8409 | 1.0000 | 0.5333 |
+| ambiguity recall | 0.9737 | 1.0000 | 0.8889 |
+| ambiguity F1 | 0.9024 | 1.0000 | 0.6666 |
+| multi-operation exact-match | 0.9000 | 1.0000 | 0.0000 |
+| scenario exact-match | 1.0000 | 1.0000 | n/a |
+| runtime execution success (executable preds) | 1.0000 | 1.0000 | 1.0000 |
+| semantic-rejection correctness | 1.0000 | 1.0000 | 1.0000 |
+
+**Do not read the overall numbers as a headline score.** They are a blend of a
+saturated core set and a deliberately hard stress set. The core row shows what the
+baseline reliably does; the stress row shows where a fixed rule set breaks.
+
+## Known failure cases (from the stress subset)
+
+Every current stress failure is one of two kinds — and **11 of 12 are conservative
+refusals, never an invented number**:
+
+- **Refuses (safe):** `valid → ambiguous` on phrasing outside the rule set —
+  fractions/idioms ("Reduce COGS by a fifth", "Double the unit price", "Halve
+  inventory"), an unlisted-target reference ("Increase AP by R2,000,000", "Reduce
+  the wage bill by 6%"), and an unlisted additive idiom ("Add R5,000,000 to opex").
+- **Refuses (safe):** `unsupported → ambiguous` on out-of-domain phrasing the
+  vocabulary does not list ("Spin off the retail division", "Issue new equity",
+  "Relocate the head office", "Replace the CEO").
+- **Value errors (status still valid):** an unlisted direction verb defaults the
+  sign to positive ("Slash opex by 12%" is parsed as +12%), and a magnitude suffix
+  on a digit is not expanded ("Increase opex by R5m" is parsed as R5, not R5m).
+- **The one genuinely unsafe failure:** "Grow cogs by 4% but also reduce cogs by 2%"
+  is parsed as a single +4% change because `but also` is not a clause separator, so
+  the conflicting second operation is dropped instead of triggering `ambiguous`.
+  This is the only stress case where the baseline commits to a number it should have
+  refused; it is tracked for a future fix.
+
+## Limitations
+
+This is a fixed rule set — a hand-authored alias table, a small number-word
+vocabulary, keyword-anchored regexes — **not** a trained model. Any phrasing outside
+what is enumerated in `src/finir_intent/baseline.py` falls back to `ambiguous`
+rather than being guessed. It does not handle: fractional/idiomatic magnitudes ("a
+fifth", "double", "halve"), magnitude suffixes on digits (`R5m`, `$2m`, `R1.2bn`),
+unlisted direction verbs (slash/shave/ramp/shrink…), unlisted target aliases,
+period/time scoping (forbidden by the v1.0 contract), or conflicting operations
+joined by connectives other than `and`/`,`/`;`. Growing FinIR-IntentBench with new
+adversarial paraphrases (as the stress subset does) is the honest way to keep
+measuring this gap rather than hide it.
+
+## Fixed parser issues (regression-tested)
+
+- **Word-boundary matching** for direction and unsupported words: naive substring
+  checks previously false-positived on ordinary English ("up" inside
+  "supplier"/"group" flipped a decrease's sign; "merge" inside "emergency" and "sue"
+  inside "issue" misclassified valid instructions as `unsupported`).
+- **`set <money-target> to N%`** now refuses (`ambiguous`) instead of silently
+  becoming a relative change.
+- **Spelled-out numbers** ("five percent", "five million rand") parse via a small
+  fixed number-word vocabulary.
+- **`trim`/`trims`** added to the down-direction words ("trim cogs by 4 percent" →
+  −4%).
+- **`boost`/`boosts`, `raises`** added to the up-direction words.
+- **Layoff/going-public phrasings with a number or filler between the trigger
+  words** ("fire 100 employees", "take the company public") are now correctly
+  `unsupported`, anchored to headcount/listing nouns so "fire up the pipeline" is not
+  a false positive.
+
+All are covered by unit tests in `tests/test_baseline.py` and by dataset entries.
+
+## License
+
+Apache-2.0, matching the core FinIR repository. The benchmark is entirely synthetic;
+no real company or personal data.
+
+## Repository & dependency
+
+- Source & docs: https://github.com/Olyxee/finir (workstream under `finir_intent/`)
+- Runtime dependency: `finir>=0.1.0,<0.2.0` — `pip install finir`
+- Intent Contract spec: `docs/intent-contract.md`, `docs/huggingface-intent-handoff.md`
+
+## Attribution
+
+The FinIR-Intent Hugging Face workstream (baseline, benchmark, evaluation, Space) was
+contributed by **Alisha Fatima** ([@AlishaFatima16](https://github.com/AlishaFatima16)).
+The core FinIR runtime and the canonical FinIR Intent Contract are maintained by
+Olyxee.
+
+
+## Links
+
+- **FinIR runtime (PyPI):** https://pypi.org/project/finir/ — `pip install finir`
+- **FinIR source (GitHub):** https://github.com/Olyxee/finir
+- **FinIR-IntentBench (dataset):** https://huggingface.co/datasets/Olyxee/FinIR-IntentBench
+- **FinIR Space (demo):** https://huggingface.co/spaces/Olyxee/FinIR-Intent-Demo

pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "finir-intent"
+dynamic = ["version"]
+description = "FinIR-Intent: natural-language financial instructions to the canonical FinIR Intent Contract."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+# FinIR-Intent (the Hugging Face natural-language workstream) was contributed by
+# Alisha Fatima (@AlishaFatima16). No private email is recorded here by request; the
+# public author string can be adjusted later if needed.
+authors = [{ name = "Alisha Fatima (@AlishaFatima16)" }]
+maintainers = [{ name = "Olyxee" }]
+keywords = ["finir", "financial-nlp", "structured-generation", "hugging-face"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+]
+
+dependencies = [
+    # Compatible FinIR runtime (published on PyPI). The contract range is stated in
+    # docs/huggingface-intent-handoff.md and src/finir_intent/_version.py.
+    "finir>=0.1.0,<0.2.0",
+]
+
+[project.optional-dependencies]
+space = ["gradio>=4.0"]
+dev = [
+    "pytest>=8.1",
+    "jsonschema>=4.21",
+]
+
+[tool.hatch.version]
+path = "src/finir_intent/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/finir_intent"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests", "eval", "space"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "SIM", "RUF"]
+ignore = ["E501"]  # line length is owned by the formatter, matching the core finir repo
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

src/finir_intent/__init__.py

@@ -0,0 +1,25 @@
+"""FinIR-Intent: the Hugging Face natural-language layer for the FinIR project.
+
+This package *interprets* natural-language financial instructions into the
+canonical FinIR Intent Contract (schema version 1.0) defined by the core ``finir``
+package (``finir.intent``). It performs no financial computation itself -- that is
+the FinIR runtime's job, reached via ``finir.intent.execute_intent`` /
+``FinancialModel.apply_intent``.
+
+    from finir_intent import compile_intent
+    from finir.intent import FinIRIntent
+
+    envelope = compile_intent("Increase COGS by 4%")
+    intent = FinIRIntent.from_obj(envelope)  # structural validation (core package)
+"""
+
+from __future__ import annotations
+
+from .baseline import BaselineIntentCompiler, compile_intent
+from .reference_model import build_reference_model
+
+__all__ = [
+    "BaselineIntentCompiler",
+    "build_reference_model",
+    "compile_intent",
+]

src/finir_intent/_version.py

@@ -0,0 +1,12 @@
+"""Version metadata for finir-intent (the Hugging Face workstream package)."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# The FinIR Intent Contract schema version this baseline emits.
+INTENT_SCHEMA_VERSION = "1.0"
+
+# The FinIR core runtime compatibility range this baseline was built against
+# (must match docs/huggingface-intent-handoff.md in the finir repo).
+FINIR_RUNTIME_COMPATIBLE = ">=0.1.0,<0.2.0"

src/finir_intent/baseline.py

@@ -0,0 +1,604 @@
+"""FinIR-Intent baseline: a deterministic, rule-based NL -> FinIR Intent compiler.
+
+This is the constrained structured-output baseline for the first milestone (see
+docs/huggingface-intent-handoff.md in the FinIR repo). It is intentionally *not* a
+trained model: a small, fully offline, dependency-free pattern matcher that emits
+exactly the canonical envelope defined by ``finir.intent`` -- the same JSON Schema
+and Python types the core runtime already validates and executes.
+
+Design boundary (do not blur this):
+
+* This module only *interprets* natural language into the canonical envelope.
+* It never performs financial arithmetic beyond parsing a number out of text.
+* It never invents a quantity for vague language -- that maps to ``ambiguous``.
+* It never guesses which of several conflicting operations on the same target the
+  user meant -- that also maps to ``ambiguous`` rather than silently picking one.
+* Target names, units and the operation vocabulary are exactly the ones in
+  ``finir.intent.schema`` / ``schemas/finir-intent-v1.schema.json``. No new fields,
+  no alias resolution inside the contract -- alias resolution happens here, before
+  the envelope is emitted, exactly as ``docs/intent-contract.md`` requires.
+
+Supported phrasing is deliberately narrow and documented in MODEL_CARD.md. Natural
+language outside these patterns correctly falls back to ``ambiguous`` (a target was
+named but no parseable quantity was found) rather than being guessed.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from finir.intent import SCHEMA_VERSION, IntentCompiler
+
+# --------------------------------------------------------------------------- targets
+# Canonical target -> the finance "kind" used to decide default unit/currency
+# handling. This mirrors 1:1 the input types declared in
+# finir_intent.reference_model.build_reference_model(), so every "valid" envelope
+# this baseline emits is also executable end-to-end against that model.
+_TARGET_KIND: dict[str, str] = {
+    "revenue": "money",
+    "cogs": "money",
+    "opex": "money",
+    "payment_terms": "days",
+    "accounts_payable": "money",
+    "inventory": "money",
+    "capex": "money",
+    "debt": "money",
+    "interest_rate": "percentage",
+    "cash": "money",
+    "price": "money",
+    "volume": "quantity",
+}
+
+# NL synonym -> canonical target (model input node name). This alias table lives
+# entirely in the interpretation layer -- the runtime resolves no aliases
+# (docs/intent-contract.md "Targets").
+_TARGET_ALIASES: dict[str, str] = {
+    "revenue": "revenue",
+    "sales": "revenue",
+    "top line": "revenue",
+    "cogs": "cogs",
+    "cost of goods sold": "cogs",
+    "cost of goods": "cogs",
+    "cost of sales": "cogs",
+    "supplier cost": "cogs",
+    "supplier costs": "cogs",
+    "opex": "opex",
+    "operating expenses": "opex",
+    "operating expense": "opex",
+    "operating costs": "opex",
+    "payment terms": "payment_terms",
+    "customer payment terms": "payment_terms",
+    "receivable terms": "payment_terms",
+    "credit terms": "payment_terms",
+    "accounts payable": "accounts_payable",
+    "trade payables": "accounts_payable",
+    "payables balance": "accounts_payable",
+    "amount owed to suppliers": "accounts_payable",
+    "supplier invoices": "accounts_payable",
+    "inventory levels": "inventory",
+    "inventory": "inventory",
+    "stock levels": "inventory",
+    "stock": "inventory",
+    "capital expenditure": "capex",
+    "capital expenditures": "capex",
+    "capital spending": "capex",
+    "capex": "capex",
+    "borrowings": "debt",
+    "loan balance": "debt",
+    "total debt": "debt",
+    "debt": "debt",
+    "interest rate": "interest_rate",
+    "cost of debt": "interest_rate",
+    "borrowing rate": "interest_rate",
+    "cash balance": "cash",
+    "cash on hand": "cash",
+    "cash position": "cash",
+    "cash": "cash",
+    "unit price": "price",
+    "selling price": "price",
+    "sale price": "price",
+    "price": "price",
+    "sales volume": "volume",
+    "unit volume": "volume",
+    "units sold": "volume",
+    "volume": "volume",
+}
+_SORTED_ALIASES = sorted(_TARGET_ALIASES, key=len, reverse=True)
+
+_UP_WORDS = (
+    "increase",
+    "increases",
+    "raise",
+    "raises",
+    "grow",
+    "grows",
+    "rise",
+    "rises",
+    "up",
+    "higher",
+    "extend",
+    "boost",
+    "boosts",
+)
+_DOWN_WORDS = (
+    "decrease",
+    "decreases",
+    "reduce",
+    "reduces",
+    "cut",
+    "cuts",
+    "trim",
+    "trims",
+    "lower",
+    "drop",
+    "drops",
+    "down",
+    "fall",
+    "falls",
+)
+# Word-boundary matching is required here: naive substring checks on these short
+# words false-positive constantly in ordinary English (e.g. "up" inside "supplier"
+# or "group", "down" inside "downside", "cut" inside "circuit").
+_UP_RE = re.compile(r"\b(?:" + "|".join(_UP_WORDS) + r")\b")
+_DOWN_RE = re.compile(r"\b(?:" + "|".join(_DOWN_WORDS) + r")\b")
+
+# Requests that are clear but cannot be expressed as a FinIR model mutation --
+# distinct from "ambiguous" (right domain, missing quantity). See
+# docs/intent-contract.md section 7 / docs/huggingface-intent-handoff.md section 7.
+_UNSUPPORTED_WORDS = (
+    "acquire",
+    "acquires",
+    "acquiring",
+    "acquired",
+    "acquisition",
+    "acquisitions",
+    "merge",
+    "merges",
+    "merging",
+    "merged",
+    "merger",
+    "mergers",
+    "hire",
+    "hires",
+    "hiring",
+    "hired",
+    "fire staff",
+    "fire employees",
+    "fired staff",
+    "fired employees",
+    "lay off",
+    "laying off",
+    "laid off",
+    "layoff",
+    "layoffs",
+    "ipo",
+    "go public",
+    "going public",
+    "buy back",
+    "buying back",
+    "bought back",
+    "buyback",
+    "buybacks",
+    "share buyback",
+    "litigation",
+    "lawsuit",
+    "lawsuits",
+    "sue",
+    "sues",
+    "sued",
+    "suing",
+    "bankrupt",
+    "bankruptcy",
+    "restructure the board",
+    "new ceo",
+)
+# Word-boundary matching: a naive substring check false-positives on ordinary
+# English containing these as a fragment (e.g. "merge" inside "emergency", "sue"
+# inside "issue", "fire" inside "fired up about revenue growth" is fine but "fire"
+# bare must not match inside e.g. "firewall" or "fireside").
+_UNSUPPORTED_RE = re.compile(r"\b(?:" + "|".join(re.escape(w) for w in _UNSUPPORTED_WORDS) + r")\b")
+
+# Multi-word unsupported phrases where a number or a couple of filler words can sit
+# between the trigger words, so a flat word list can't catch them (e.g. "fire 100
+# employees", "take the company public"). Anchored to headcount/listing nouns so
+# they don't false-positive on ordinary English ("fire up the sales pipeline" has no
+# employees/staff/... noun, so it does not match).
+_UNSUPPORTED_PATTERNS = (
+    re.compile(
+        r"\bfir(?:e|es|ed|ing)\b(?:\s+\w+){0,3}\s+(?:employees|workers|staff|people|headcount)\b"
+    ),
+    re.compile(r"\b(?:take|takes|taking|took)\b(?:\s+\w+){0,3}\s+public\b"),
+    re.compile(r"\bgo(?:es|ing)?\s+public\b"),
+    re.compile(r"\bpublic\s+(?:offering|listing)\b"),
+    re.compile(r"\blist(?:s|ed|ing)?\s+on\s+the\s+(?:stock\s+)?exchange\b"),
+    re.compile(r"\b(?:cut|cuts|reduce|reduces|slash|slashes)\s+headcount\b"),
+)
+
+# Spelled-out cardinal numbers (deterministic, exact parsing of an unambiguous
+# number phrase -- not a guess). Kept small and targeted: only the words needed to
+# resolve a spelled-out number, never a general vocabulary.
+_NUM_WORDS: dict[str, int] = {
+    "zero": 0,
+    "one": 1,
+    "two": 2,
+    "three": 3,
+    "four": 4,
+    "five": 5,
+    "six": 6,
+    "seven": 7,
+    "eight": 8,
+    "nine": 9,
+    "ten": 10,
+    "eleven": 11,
+    "twelve": 12,
+    "thirteen": 13,
+    "fourteen": 14,
+    "fifteen": 15,
+    "sixteen": 16,
+    "seventeen": 17,
+    "eighteen": 18,
+    "nineteen": 19,
+    "twenty": 20,
+    "thirty": 30,
+    "forty": 40,
+    "fifty": 50,
+    "sixty": 60,
+    "seventy": 70,
+    "eighty": 80,
+    "ninety": 90,
+}
+_NUM_SCALES: dict[str, int] = {
+    "hundred": 100,
+    "thousand": 1_000,
+    "million": 1_000_000,
+    "billion": 1_000_000_000,
+}
+_NUM_WORD_ALT = "|".join(sorted({*_NUM_WORDS, *_NUM_SCALES}, key=len, reverse=True))
+
+_PCT_RE = re.compile(r"([+-]?\d+(?:\.\d+)?)\s*(?:%|\bpercent\b)")
+# Only a phrase built entirely from recognized number/scale words is captured --
+# deliberately not a generic "any words before percent" grab, which would swallow
+# unrelated leading words (e.g. "up" in "bump ... up five percent").
+_SPELLED_PCT_RE = re.compile(
+    rf"\b((?:{_NUM_WORD_ALT})(?:[ -](?:{_NUM_WORD_ALT}))*)\s+percent\b", re.I
+)
+_SPELLED_MONEY_RE = re.compile(
+    rf"^((?:{_NUM_WORD_ALT})(?:[ -](?:{_NUM_WORD_ALT}))*)\s*(rand|rands|dollars?|zar|usd)?\s*\.?\s*$",
+    re.I,
+)
+_DAYS_RANGE_RE = re.compile(r"\b(\d+)\s*(?:to|->|→)\s*(\d+)\s*days?\b")
+_DAYS_TO_RE = re.compile(r"\bto\s+(\d+)\s*days?\b")
+_BY_RE = re.compile(r"\bby\s+(.+)$")
+_TO_RE = re.compile(r"\bto\s+(.+)$")
+_MONEY_AMOUNT_RE = re.compile(r"(r|zar|usd|\$)?\s*([\d]+(?:\.\d+)?)\s*(zar|usd)?", re.I)
+_RANGE_RE = re.compile(
+    r"\b(?:range|sweep|grid|scan|explore)\b.*?\b(?:from|between)\b\s*(?:r|zar|usd|\$)?\s*([\d.]+)"
+    r"\s*(?:zar|usd)?\s*\b(?:to|and)\b\s*(?:r|zar|usd|\$)?\s*([\d.]+)\s*(?:zar|usd)?.*?\b(\d+)\s*(?:steps|points)\b",
+    re.I | re.S,
+)
+_SCENARIO_SPLIT_RE = re.compile(r"([A-Za-z][A-Za-z ]{0,24}?)\s+scenario\s*:\s*", re.I)
+_NO_CHANGE_BODY = {
+    "no change",
+    "no changes",
+    "none",
+    "base",
+    "unchanged",
+    "the base case",
+    "base case",
+}
+
+
+def _strip_thousands(text: str) -> str:
+    """Remove thousand-separator commas from numbers (``5,000,000`` -> ``5000000``)."""
+    return re.sub(r"(?<=\d),(?=\d{3}\b)", "", text)
+
+
+def _amount(raw: str) -> float:
+    return float(re.sub(r"[^\d.]", "", raw))
+
+
+def _currency(*fragments: str | None) -> str | None:
+    for frag in fragments:
+        if not frag:
+            continue
+        low = frag.strip().lower()
+        if low in ("r", "zar", "rand", "rands"):
+            return "ZAR"
+        if low in ("$", "usd", "dollar", "dollars"):
+            return "USD"
+    return None
+
+
+def _words_to_number(phrase: str) -> float | None:
+    """Convert a spelled-out cardinal number phrase (e.g. 'five million') to a
+    float. Deterministic, exact parsing of an unambiguous number -- not a guess.
+    Returns None if any token isn't a recognized number/scale word.
+    """
+    tokens = phrase.strip().lower().replace("-", " ").split()
+    if not tokens:
+        return None
+    total = 0
+    current = 0
+    for t in tokens:
+        if t == "and":
+            continue
+        if t in _NUM_WORDS:
+            current += _NUM_WORDS[t]
+        elif t in _NUM_SCALES:
+            scale = _NUM_SCALES[t]
+            if scale == 100:
+                current = (current or 1) * scale
+            else:
+                total += (current or 1) * scale
+                current = 0
+        else:
+            return None
+    return float(total + current)
+
+
+def _direction_sign(low: str) -> float:
+    up = bool(_UP_RE.search(low))
+    down = bool(_DOWN_RE.search(low))
+    return -1.0 if (down and not up) else 1.0
+
+
+def _find_target(low: str) -> str | None:
+    for alias in _SORTED_ALIASES:
+        if re.search(r"\b" + re.escape(alias) + r"\b", low):
+            return _TARGET_ALIASES[alias]
+    return None
+
+
+def _split_clauses(text: str) -> list[str]:
+    protected = _strip_thousands(text)
+    parts = re.split(r"\s*;\s*|\s*,\s*(?=[A-Za-z])|\s+\band\b\s+", protected)
+    clauses = []
+    for p in parts:
+        p = re.sub(r"^(and|then|also)\s+", "", p.strip(), flags=re.I).strip(" .")
+        if p:
+            clauses.append(p)
+    return clauses
+
+
+def _parse_clause(clause: str) -> tuple[dict[str, Any] | None, str | None]:
+    """Parse one clause. Returns (operation, note); note is set only on failure."""
+    low = clause.lower()
+    target = _find_target(low)
+    if target is None:
+        return None, None
+    kind = _TARGET_KIND.get(target, "money")
+
+    m = _DAYS_RANGE_RE.search(low)
+    if m:
+        return {
+            "operation": "set",
+            "target": target,
+            "value": _amount(m.group(2)),
+            "unit": "days",
+        }, None
+
+    m = _DAYS_TO_RE.search(low)
+    if m:
+        return {
+            "operation": "set",
+            "target": target,
+            "value": _amount(m.group(1)),
+            "unit": "days",
+        }, None
+
+    # "set/reduce/... TARGET to N%" is an absolute set to that percentage level
+    # (new = value), not a relative_change -- must be checked before the generic
+    # relative-change percentage rule below.
+    m_to = _TO_RE.search(low)
+    if m_to:
+        pct = _PCT_RE.match(m_to.group(1).strip())
+        if pct and kind == "percentage":
+            return (
+                {
+                    "operation": "set",
+                    "target": target,
+                    "value": _amount(pct.group(1)) / 100.0,
+                    "unit": "percentage",
+                },
+                None,
+            )
+        if pct:
+            # "set/change <non-percentage target> to N%" (e.g. "set opex to 45%") is
+            # not a coherent instruction for this target's type -- refuse rather
+            # than silently reinterpreting "to" as "by" (relative_change), which
+            # would invent a meaning the user did not state.
+            return None, "target_no_value"
+
+    m = _PCT_RE.search(low)
+    if m:
+        value = _direction_sign(low) * _amount(m.group(1)) / 100.0
+        return {"operation": "relative_change", "target": target, "value": value}, None
+
+    m = _SPELLED_PCT_RE.search(low)
+    if m:
+        if m_to and _SPELLED_PCT_RE.match(m_to.group(1).strip()):
+            # Same "set X to <percent>" guard as the digit case above -- a
+            # spelled-out number must not bypass it.
+            return None, "target_no_value"
+        num = _words_to_number(m.group(1))
+        if num is not None:
+            value = _direction_sign(low) * num / 100.0
+            return {"operation": "relative_change", "target": target, "value": value}, None
+
+    m = _BY_RE.search(low)
+    if m and kind == "money":
+        amt_match = _MONEY_AMOUNT_RE.search(m.group(1))
+        if amt_match and amt_match.group(2):
+            amt = _amount(amt_match.group(2))
+            sign = -1.0 if _direction_sign(low) < 0 else 1.0
+            op: dict[str, Any] = {
+                "operation": "absolute_change",
+                "target": target,
+                "value": sign * amt,
+            }
+            ccy = _currency(amt_match.group(1), amt_match.group(3))
+            if ccy:
+                op["currency"] = ccy
+            return op, None
+        spelled = _SPELLED_MONEY_RE.match(m.group(1).strip())
+        if spelled:
+            num = _words_to_number(spelled.group(1))
+            if num is not None:
+                sign = -1.0 if _direction_sign(low) < 0 else 1.0
+                op = {"operation": "absolute_change", "target": target, "value": sign * num}
+                ccy = _currency(spelled.group(2))
+                if ccy:
+                    op["currency"] = ccy
+                return op, None
+
+    if m_to and kind in ("money", "days"):
+        amt_match = _MONEY_AMOUNT_RE.search(m_to.group(1))
+        if amt_match and amt_match.group(2):
+            amt = _amount(amt_match.group(2))
+            op = {"operation": "set", "target": target, "value": amt}
+            if kind == "money":
+                ccy = _currency(amt_match.group(1), amt_match.group(3))
+                if ccy:
+                    op["currency"] = ccy
+            else:  # days, without the word "days" already matched above
+                op["unit"] = "days"
+            return op, None
+    # kind == "quantity": a plain numeric "set ... to N" is left unhandled (unit
+    # intentionally never guessed for quantity targets -- see MODEL_CARD.md "known
+    # limitations": the runtime's semantic validator only accepts unit == 'scalar'
+    # or no unit for Quantity-typed targets today).
+
+    return None, "target_no_value"
+
+
+def _envelope(
+    status: str, *, operations: list[dict[str, Any]] | None = None, reason: str | None = None
+) -> dict[str, Any]:
+    env: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "status": status,
+        "operations": operations or [],
+    }
+    if reason is not None:
+        env["reason"] = reason
+    return env
+
+
+def _is_unsupported(low: str) -> bool:
+    if _UNSUPPORTED_RE.search(low):
+        return True
+    return any(pat.search(low) for pat in _UNSUPPORTED_PATTERNS)
+
+
+def _try_parse_scenarios(text: str) -> dict[str, Any] | None:
+    parts = _SCENARIO_SPLIT_RE.split(text)
+    if len(parts) < 3:
+        return None
+    preamble = parts[0].strip(" .")
+    if preamble and len(preamble.split()) > 8:
+        return None
+
+    scenarios: list[dict[str, Any]] = []
+    for i in range(1, len(parts), 2):
+        name = re.sub(r"\s+", "_", parts[i].strip().lower())
+        body = parts[i + 1].strip(" .") if i + 1 < len(parts) else ""
+        if not body or body.lower() in _NO_CHANGE_BODY:
+            scenarios.append({"name": name, "operations": []})
+            continue
+        ops: list[dict[str, Any]] = []
+        unparsed = False
+        for clause in _split_clauses(body):
+            op, _note = _parse_clause(clause)
+            if op is not None:
+                if op["operation"] == "range":
+                    return None  # range is never valid inside a scenario
+                ops.append(op)
+            else:
+                unparsed = True
+        if unparsed and not ops:
+            return None  # can't confidently build this scenario -> fall through to ambiguous
+        targets = [o["target"] for o in ops]
+        if len(targets) != len(set(targets)):
+            return None
+        scenarios.append({"name": name, "operations": ops})
+
+    if len(scenarios) < 2:
+        return None
+    return {"schema_version": SCHEMA_VERSION, "status": "valid", "scenarios": scenarios}
+
+
+def compile_intent(text: str) -> dict[str, Any]:
+    """Compile one natural-language financial instruction into a canonical envelope.
+
+    Always returns a dict that structurally validates against
+    ``finir.intent.json_schema()`` (verify with
+    ``finir.intent.FinIRIntent.from_obj`` before executing).
+    """
+    scenario_env = _try_parse_scenarios(text)
+    if scenario_env is not None:
+        return scenario_env
+
+    low = text.lower()
+    if _is_unsupported(low):
+        return _envelope(
+            "unsupported",
+            reason=f"request cannot be represented as a FinIR model mutation: {text!r}",
+        )
+
+    range_match = _RANGE_RE.search(_strip_thousands(low))
+    if range_match:
+        target = _find_target(low)
+        if target is not None:
+            return _envelope(
+                "valid",
+                operations=[
+                    {
+                        "operation": "range",
+                        "target": target,
+                        "min": _amount(range_match.group(1)),
+                        "max": _amount(range_match.group(2)),
+                        "steps": int(range_match.group(3)),
+                    }
+                ],
+            )
+
+    ops: list[dict[str, Any]] = []
+    saw_target_without_value = False
+    for clause in _split_clauses(text):
+        op, note = _parse_clause(clause)
+        if op is not None:
+            ops.append(op)
+        elif note == "target_no_value":
+            saw_target_without_value = True
+
+    if not ops:
+        if saw_target_without_value:
+            return _envelope(
+                "ambiguous",
+                reason="a financial target was identified but no quantitative change was specified",
+            )
+        return _envelope(
+            "ambiguous", reason="no financial target or quantitative change was identified"
+        )
+
+    targets = [o["target"] for o in ops]
+    if len(targets) != len(set(targets)):
+        return _envelope(
+            "ambiguous",
+            reason="conflicting operations on the same target were requested; cannot resolve unambiguously",
+        )
+
+    return _envelope("valid", operations=ops)
+
+
+class BaselineIntentCompiler(IntentCompiler):
+    """The FinIR-Intent baseline, implementing the core :class:`IntentCompiler` seam.
+
+    Deterministic and fully offline -- no external LLM/API dependency. Emits exactly
+    the canonical envelope; validation and execution are left entirely to
+    ``finir.intent`` / ``FinancialModel.apply_intent`` (never duplicated here).
+    """
+
+    def compile(self, text: str) -> dict[str, Any]:
+        return compile_intent(text)

src/finir_intent/reference_model.py

@@ -0,0 +1,36 @@
+"""A small demo :class:`~finir.FinancialModel` spanning every FinIR-IntentBench target.
+
+This is fixture data for the Hugging Face workstream's end-to-end proof and the
+Space demo -- not a real company's financials. It exists so every target the
+baseline compiler can name (see ``finir_intent.baseline._TARGET_KIND``) is a real
+input the runtime can execute against. Built entirely from the public
+``finir.FinancialModel`` API; it adds no new runtime behavior and duplicates no
+execution logic.
+"""
+
+from __future__ import annotations
+
+from finir import FinancialModel
+
+
+def build_reference_model() -> FinancialModel:
+    m = FinancialModel(name="finir_intent_reference")
+    m.input("revenue", 500_000_000, currency="ZAR")
+    m.input("cogs", 300_000_000, currency="ZAR")
+    m.input("opex", 120_000_000, currency="ZAR")
+    m.input("payment_terms", 30, type="days")
+    m.input("accounts_payable", 40_000_000, currency="ZAR")
+    m.input("inventory", 50_000_000, currency="ZAR")
+    m.input("capex", 60_000_000, currency="ZAR")
+    m.input("debt", 200_000_000, currency="ZAR")
+    m.input("interest_rate", 0.09, type="percentage")
+    m.input("cash", 80_000_000, currency="ZAR")
+    m.input("price", 1_250, currency="ZAR")
+    m.input("volume", 400_000, type="quantity[units]")
+
+    m.define("gross_profit", "revenue - cogs")
+    m.define("gross_margin", "gross_profit / revenue", output=True)
+    m.define("ebitda", "gross_profit - opex", output=True)
+    m.define("interest_expense", "debt * interest_rate", output=True)
+    m.define("net_cash_position", "cash - capex", output=True)
+    return m