ferric-fred

ferric-fred

A strongly-typed Rust client for FRED — theFederal Reserve Economic Data service from the Federal Reserve Bank of St. Louis— plus a CLI (with TUI charts) and an MCP server built on top of it.

ferric (iron oxide → rust) + FRED. Iron-clad, typed access to economic data.

Workspace

A Cargo workspace of three crates — each with its own README (the crates.io /docs.rs landing page) that carries the full usage detail:

Published versions (these badges are the source of truth — the crates versionindependently, so they can drift out of lockstep):

Consumers depend on the library by workspace path, so a breaking change inthe library cannot compile-pass its consumers without updating them — thatcompile-time coupling is the primary "stay in sync" guarantee (versions aremanaged on top; see the ADRs).

What it covers

The library wraps all of FRED's read endpoints — series and observations(including ALFRED point-in-time / vintage data via a real-time window),search, categories, releases (including the nested release-table tree, withoptional inline observation values), sources,and tags — plus the GeoFRED / Maps API (regional data and the geographicshape files to map it, ADR-0025) — behindergonomic builders, with newtype identifiers, typed enums forFRED's closed value sets, a non-panicking error taxonomy, and auto-pagination(Paginate::send_all walks an endpoint to exhaustion, Paginate::stream yieldslazily; --all on the CLI). See ADR-0020 andADR-0021.

GeoFRED support spans the library, CLI (fred geofred), and MCP(get_regional_data, get_series_data, get_series_group) layers. The oneexception is the geographic shapes/file endpoint, which is library/CLI-only —a large projected-GeoJSON blob is poor ergonomics for an MCP tool caller(ADR-0025).

Pick an entry point:

• Library — cargo add ferric-fred; typed async access from your own code.See the crate README anddocs.rs.
• CLI (fred) — cargo install ferric-fred-cli; search, show metadata,print or chart observations in the terminal, browse categories,releases, sources, and tags, and pull GeoFRED regional data and map shapes(fred geofred). See the crate READMEor fred <command> --help.
• MCP server (fred-mcp) — cargo install ferric-fred-mcp; 34 tools overstdio covering the same read surface, for MCP-capable clients (ADR-0010).Each tool declares input and output schemas plus behavioural annotations(ADR-0023). See thecrate README.

The MCP server is listed and scored on:

Development

A Nix flake provides a reproducible toolchain (nix develop, or direnv allowonce), but the project builds with a plain Rust toolchain too — Nix supplies theenvironment, not the build (ADR-0008).

Contributor setup, the fmt/clippy/test gate, the tracked git hooks, and theworkflow for adding an endpoint live in CONTRIBUTING.md.CI (ci.yml) runs that same offline gate on every push and PR; a dormantlive.yml runs the live FRED tests once an Infisical machine identity isconfigured (ADR-0016).

Benchmarks

Performance tooling from the org Tech Radar pilot(ADR-0026, issue #42):

# Deserialization microbenches (divan) — the observations parse hot path.
cargo bench -p ferric-fred --bench deserialization
# Same workload under criterion (the divan-vs-criterion baseline).
cargo bench -p ferric-fred --bench deserialization_criterion

# Headless `fred chart` render cost (divan + ratatui TestBackend, no tty).
cargo bench -p ferric-fred-cli --bench render

# CLI wall-clock timing (hyperfine): startup + a live fetch-and-render.
# The fetch benchmark needs FRED_API_KEY; startup runs offline.
scripts/bench-cli.sh                    # add --json DIR to export hyperfine JSON

CI keeps the benches compiling on every PR (cargo bench --no-run), and aseparate bench.yml uploads results to Bencher (hostedproject ferric-fred) to track them over time and flag regressions on PRs.Bencher has no divan adapter, so it ingests the criterion mirror(rust_criterion) and hyperfine startup (shell_hyperfine); divan stays thefast local harness. BENCHER_API_TOKEN comes from Infisical, so the upload is ano-op until the machine identity is configured — seeADR-0026.

Secrets

The client reads a free FRED API key from the FRED_API_KEY environmentvariable (get one at https://fredaccount.stlouisfed.org/apikeys). Locally,secrets are injected via Infisical + direnv(ADR-0009):

cp .envrc.example .envrc     # local, git-ignored entry point
infisical login             # user auth (opens a browser)
infisical init              # link this dir → project
direnv allow                # load the shell + inject secrets on cd-in

Store the key with infisical secrets set FRED_API_KEY="…" --env=dev --path=/shared.No Infisical? Just set it directly in your git-ignored .envrc:export FRED_API_KEY="…" — the library only reads the env var and has nodependency on Infisical.

Architecture decisions

Design decisions are recorded as ADRs in docs/adr/. Start withthe index.

License

Dual-licensed under MIT OR Apache-2.0, at your option — the Rust ecosystemdefault (ADR-0006). See LICENSE-MITand LICENSE-APACHE. Unless you state otherwise, anycontribution you submit is licensed under the same dual terms (seeCONTRIBUTING.md).

This covers our code; FRED data itself is subject to the St. Louis Fed's termsof use, and you supply your own API key — the project ships no data and no key.