fredq 0.1.0__tar.gz

fredq-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Byte-compiled / optimized files
+__pycache__/
+
+# Test and coverage output
+.pytest_cache/
+.coverage
+coverage.xml
+junit*.xml
+htmlcov/
+
+# Virtual environments and uv cache
+.venv/
+.uv-cache/
+
+# Tool caches
+.ruff_cache/
+.tox/
+.mypy_cache/
+node_modules/
+
+# Editors
+.vscode/
+
+# Claude Code local state
+.claude/
+
+# Local API key material (never commit)
+.fredq-key
+fredq-key.txt
+
+# Worktrees + scratch
+.worktrees/
+output/
+tmp/
+
+# Ad-hoc fredq report fleet (generated artifacts, data dumps, builders)
+report/

fredq-0.1.0/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+## Project
+fredq exposes FRED (Federal Reserve Economic Data) HTTP endpoints as an LLM-friendly CLI that prints the raw JSON FRED returns.
+
+## Stack
+Python 3.10+, uv, httpx, argparse, pytest, pytest-httpx, ruff, pyright, tox, hatchling.
+
+## Commands
+- Install/sync: `uv sync --all-groups`
+- Run CLI: `uv run fredq --help`
+- Test single: `uv run pytest path/to/test_file.py`
+- Test all: `uv run pytest`
+- Lint: `uv run ruff check .`
+- Format: `uv run ruff format .`
+- Type check: `uv run pyright`
+- Spell check: `npm run spell` or `make spell`
+- Spell changed files: `npm run spell:changed` or `make spell-changed`
+- Full check: `uv run tox`
+
+## Architecture
+- `src/fredq/client.py` -> FRED HTTP client (single async GET, api_key injection, retries, raw response retrieval).
+- `src/fredq/auth.py` -> Read FRED_API_KEY from env or fallback file.
+- `src/fredq/commands.py` -> command metadata used to build CLI commands, validation, and help.
+- `src/fredq/params.py` -> CLI parameter coercion and validation helpers.
+- `src/fredq/cli.py` -> argparse command tree and stdout/stderr behavior.
+- `tests/` -> pytest tests mirroring `src/fredq/`.
+
+## Rules
+- IMPORTANT: `--help` is the primary product surface; keep it complete, adaptive, and generated from command metadata where practical.
+- Do not add `describe`, `endpoints`, `params`, or other discovery commands; discovery belongs under `fredq --help` and `fredq <endpoint> --help`.
+- Print FRED response bodies to stdout exactly as returned; do not model, reshape, pretty-print, or interpret endpoint JSON.
+- Keep FRED endpoint knowledge in metadata and validation only; do not create response classes.
+- Use `uv run python` for Python scripts; never use bare `python` or `python3`.
+- Never log or print the FRED API key.
+- Keep runtime dependencies narrow; do not add TUI, ORM, web framework, or rich formatting libraries.
+
+## API key
+- Primary: `FRED_API_KEY` environment variable.
+- Fallback: file at `~/.fredq/api_key` (single line, key only).
+- The CLI must redact the key from any error messages and never log it.
+
+## Help text
+When adding or editing a CLI command:
+1. **Summary**: active verb, ≤68 chars (over wraps two-line in top-level help). `Fetch` (data), `List` (catalog), `Search` (text), `Show` (single entity), `Discover` (curated). Pair sibling commands with the same verb.
+2. **Description**: describe response content, not fredq mechanics. Forbidden phrasings: `Calls FRED`, `writes to stdout`, `response-model mapping`. The root parser already covers output behavior. Do not paraphrase the summary.
+3. **Notes**: real clarifications only — FRED quirks, switch-behavior surprises, dependencies. Drop diary entries and redundant restatements.
+4. **Order in `COMMANDS` tuple by importance**: daily-driver → discovery → entity lookups → schema introspection. Never append to the end.
+5. **Param boilerplate is shared** (`--api-key`, `--realtime-start`, `--realtime-end` use exact strings — copy them). Run `pytest -k help` before and after.
+
+## Output formats
+- **Default**: raw FRED JSON to stdout, exactly as returned.
+- **Parquet**: opt-in via `--format parquet --out PATH`, `series-observations` only. Parses the response into a typed table (`date`, `value`, realtime bounds) with the response envelope stored as schema metadata. Other endpoints reject `--format parquet` with a usage error.
+- Other endpoints stay JSON-only.
+
+## Workflow
+- Make minimal changes and avoid unrelated refactors.
+- When adding a command or parameter, update validation, adaptive help, and tests in the same change.
+- Prefer focused unit tests with mocked HTTP; mark live FRED tests as integration.
+- Before considering code changes done, run `uv run tox`. It is the expected bundled verification for formatting, lint, type check, tests, and spelling.
+- For command or parameter changes, also run the app against FRED after `tox`:
+  - `uv run fredq <command> --help`
+  - `uv run fredq <command> <minimal required parameters>`
+  - `uv run fredq <command> <parameters with each supported date format when dates are involved>`
+  - `uv run fredq <command> <parameters with meaningful values that could affect FRED's raw output>`
+- When a parameter has a default, test both omission and explicit override if the default affects the request sent to FRED.
+- Ask before making architectural changes that affect the CLI grammar or auth behavior.
+
+## FRED API state probes
+- When checking the current FRED API surface, use a varied set of series, releases, and categories so behavior is not inferred from one path only.
+- Baseline probe targets:
+  - Series: `GNPCA` (annual GDP), `DGS10` (10y yield), `CPIAUCSL` (CPI), `UNRATE` (unemployment), `FEDFUNDS` (fed funds), `DEXCAUS` (CAD/USD)
+  - Categories: `32991` (Money, Banking), `0` (root)
+  - Releases: `53` (GDP), `10` (CPI), `175` (Employment)
+  - Sources: `1` (Board of Governors), `3` (Bureau of Labor Statistics)
+- Add targeted probes when an endpoint is series-sensitive, but keep this baseline for broad API-surface discovery.
+
+## GeoFRED / Maps
+- Implemented under the `geofred` subcommand group (`series-group`, `series-data`, `regional-data`, `shapes`). Different base URL; regional data keyed by FIPS; `shapes` returns Highcharts-format GeoJSON in a Lambert Conformal Conic projection (not WGS84).
+
+## Out of scope
+- Mapping FRED JSON into Python domain models.
+- Separate documentation/discovery subcommands.
+- Secrets or API keys in checked-in files.

fredq-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to fredq are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+Initial release.
+
+### Added
+
+- CLI for every public FRED API endpoint, printing raw FRED JSON to stdout.
+- Endpoint-specific commands across series, search, tags, categories,
+  releases, release tables, and sources.
+- `series-observations` unit transforms (`--units`) and frequency aggregation
+  (`--frequency`).
+- ALFRED point-in-time support: `--realtime-start` / `--realtime-end` and
+  `series-vintagedates`.
+- GeoFRED / Maps regional data via the `geofred` subcommand group
+  (`series-group`, `series-data`, `regional-data`, `shapes`).
+- Typed Parquet output for `series-observations` (`--format parquet --out`),
+  via the optional `parquet` extra.
+- Adaptive `--help` generated from command metadata, with parameters, allowed
+  value sets, and examples.
+- API key resolution from `FRED_API_KEY`, `~/.fredq/api_key`, or `--api-key`,
+  with the key redacted from all errors and logs.
+- Exit-code contract: `0` success, `1` FRED request failure, `2` usage error.
+
+[Unreleased]: https://github.com/joce/fredq/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/joce/fredq/releases/tag/v0.1.0

fredq-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jocelyn Legault
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fredq-0.1.0/PKG-INFO

@@ -0,0 +1,413 @@
+Metadata-Version: 2.4
+Name: fredq
+Version: 0.1.0
+Summary: LLM-friendly CLI for raw FRED (Federal Reserve Economic Data) API JSON.
+Project-URL: Homepage, https://github.com/joce/fredq
+Project-URL: Repository, https://github.com/joce/fredq
+Project-URL: Issues, https://github.com/joce/fredq/issues
+Author-email: Jocelyn Legault <jocelynlegault@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,economic-data,federal-reserve,fred,llm-tools,macro
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Utilities
+Requires-Python: <4.0,>=3.10
+Requires-Dist: httpx<1.0,>=0.28
+Requires-Dist: typing-extensions>=4.13
+Provides-Extra: parquet
+Requires-Dist: pyarrow<25,>=15; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# fredq
+
+[![CI](https://github.com/joce/fredq/actions/workflows/ci.yml/badge.svg)](https://github.com/joce/fredq/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/joce/fredq/graph/badge.svg)](https://codecov.io/gh/joce/fredq)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![GitHub License](https://img.shields.io/github/license/joce/fredq)](https://github.com/joce/fredq/blob/main/LICENSE)
+
+FRED Query — Federal Reserve Economic Data on the command line.
+
+fredq brings the [FRED](https://fred.stlouisfed.org/docs/api/fred/) (Federal
+Reserve Economic Data) HTTP endpoints to the command line. It is built for
+scripts, agents, and quick terminal work that needs the JSON returned by the
+FRED API.
+
+The project stays deliberately close to the source. It does not reshape FRED
+responses, define economic domain models, or add a discovery API beyond CLI
+help.
+
+## Features
+
+- Raw FRED JSON on stdout, with no pretty-printing or interpretation.
+- Endpoint-specific commands for every public FRED API endpoint.
+- Generated help that includes examples, parameters, and known value sets.
+- Typed Parquet output for `series-observations` when a long time series is
+  more useful as a columnar table than as JSON.
+- ALFRED point-in-time support (`--realtime-start`, `--realtime-end`,
+  `series-vintagedates`).
+- GeoFRED / Maps regional data (`geofred` subcommands): regional time series,
+  all-region snapshots, series-group metadata, and GeoJSON shape files.
+
+## Install
+
+fredq is a Python 3.10+ project. Install it as a tool with
+[uv](https://docs.astral.sh/uv/) or with pip:
+
+```powershell
+uv tool install fredq
+# or
+pip install fredq
+```
+
+For Parquet output, include the `parquet` extra:
+
+```powershell
+uv tool install "fredq[parquet]"
+# or
+pip install "fredq[parquet]"
+```
+
+Then run:
+
+```powershell
+fredq --help
+```
+
+### From Source
+
+To run from a local checkout (development):
+
+```powershell
+uv sync --all-groups
+uv run fredq --help
+```
+
+Or install the checkout as a tool:
+
+```powershell
+uv tool install .
+fredq --help
+```
+
+## API Key
+
+The FRED API requires a free API key. Request one at
+<https://fred.stlouisfed.org/docs/api/api_key.html>.
+
+fredq reads the key from, in order:
+
+1. The `FRED_API_KEY` environment variable.
+2. The first non-empty line of `~/.fredq/api_key`.
+3. The `--api-key` flag (visible in process listings; prefer the env var).
+
+On POSIX systems, restrict the key file so only your user can read it:
+
+```bash
+chmod 600 ~/.fredq/api_key
+```
+
+fredq emits a warning if the file is readable by group or world. To disable
+the file fallback entirely (for hermetic runs), set `FREDQ_DISABLE_KEY_FILE=1`
+or pass `--no-key-file`.
+
+fredq never prints, logs, or echoes the API key. The key is also redacted
+from URLs in error messages and from any httpx debug logs emitted under
+`--verbose`.
+
+## Quick Start
+
+Show metadata for a series:
+
+```powershell
+uv run fredq series --series-id GNPCA
+```
+
+Fetch a series' observations:
+
+```powershell
+uv run fredq series-observations --series-id CPIAUCSL
+```
+
+Apply a unit transformation and frequency aggregation:
+
+```powershell
+uv run fredq series-observations --series-id CPIAUCSL --units pch --frequency m
+```
+
+Search for a series by keyword:
+
+```powershell
+uv run fredq series-search --search-text "10-year treasury" --limit 10
+```
+
+Browse the FRED category tree from the root:
+
+```powershell
+uv run fredq category-children --category-id 0
+```
+
+List recent economic releases:
+
+```powershell
+uv run fredq releases --limit 10
+```
+
+List recent release publication dates across all releases:
+
+```powershell
+uv run fredq releases-dates --limit 20
+```
+
+Show metadata for a specific release (53 = GDP):
+
+```powershell
+uv run fredq release --release-id 53
+```
+
+Find all series tagged with a set of FRED tags:
+
+```powershell
+uv run fredq tags-series --tag-names "usa;monthly;cpi" --limit 25
+```
+
+ALFRED point-in-time: see what GDP looked like on a past date:
+
+```powershell
+uv run fredq series-vintagedates --series-id GNPCA
+uv run fredq series-observations --series-id GNPCA --realtime-start 2024-09-25
+```
+
+Fetch GeoFRED regional data — per-capita income by state for one year:
+
+```powershell
+uv run fredq geofred series-group --series-id WIPCPI
+uv run fredq geofred series-data --series-id WIPCPI --start-date 2022-01-01
+```
+
+## Parquet Output
+
+`series-observations` can write a typed Parquet table instead of raw JSON.
+Install with the `parquet` extra to pull in `pyarrow`:
+
+```powershell
+uv sync --extra parquet
+```
+
+Then pass `--format parquet --out PATH`:
+
+```powershell
+uv run fredq series-observations --series-id CPIAUCSL --units pch --frequency m \
+  --format parquet --out cpi_yoy.parquet
+```
+
+On success a single JSON descriptor line goes to stdout (the file format, out
+path, row count, byte size). The Parquet schema is `date` (date32), `value`
+(float64), `realtime_start` (date32), `realtime_end` (date32). FRED's
+missing-value sentinel `.` is written as `NaN`. The full response envelope
+(count, offset, limit, observation range, units, sort order) and the request
+context (units, frequency, realtime range) are stored as schema key-value
+metadata so the table is self-describing.
+
+Parquet writes are scoped to `series-observations` only; every other command
+stays JSON-only, and rejects `--format parquet` with a usage error. Parquet
+output assumes FRED's default observation layout (one row per observation);
+fredq does not expose FRED's alternative `output_type` modes.
+
+## Commands
+
+Use root help to see the command list:
+
+```powershell
+uv run fredq --help
+```
+
+Current commands, grouped by how often they're reached for:
+
+**Daily-driver fetches**
+
+| Command | FRED data |
+| --- | --- |
+| `series` | Show metadata for one FRED series (title, units, frequency, observation range). |
+| `series-observations` | Fetch the observation values for one FRED series. |
+
+**Series discovery**
+
+| Command | FRED data |
+| --- | --- |
+| `series-search` | Search FRED series by keyword. |
+| `series-search-tags` | List tags for a series full-text search. |
+| `series-search-related-tags` | List tags related to a search and existing tag filter. |
+| `tags-series` | List series matching a set of FRED tags. |
+| `tags` | List all FRED tags. |
+| `related-tags` | List tags related to an existing tag filter. |
+
+**Series-bound analysis**
+
+| Command | FRED data |
+| --- | --- |
+| `series-vintagedates` | List vintage dates (revision dates) for one FRED series. |
+| `series-categories` | List categories that contain a given series. |
+| `series-tags` | List tags assigned to a FRED series. |
+| `series-release` | Show the release that a FRED series belongs to. |
+| `series-updates` | List recently updated FRED series. |
+
+**Category browse**
+
+| Command | FRED data |
+| --- | --- |
+| `category` | Show metadata for one FRED category. |
+| `category-children` | List child categories of a FRED category. |
+| `category-related` | List categories related to a given FRED category. |
+| `category-series` | List series belonging to one FRED category. |
+| `category-tags` | List tags for series in one FRED category. |
+| `category-related-tags` | List tags related to a category and existing tag filter. |
+
+**Releases and calendar**
+
+| Command | FRED data |
+| --- | --- |
+| `releases` | List all FRED economic data releases. |
+| `releases-dates` | List release dates across all FRED releases. |
+| `release` | Show metadata for one FRED release. |
+| `release-dates` | List publication dates for one FRED release. |
+| `release-series` | List series belonging to one FRED release. |
+| `release-sources` | List sources for one FRED release. |
+| `release-tags` | List tags for one FRED release. |
+| `release-related-tags` | List tags related to a release and existing tag filter. |
+| `release-tables` | Fetch the hierarchical data table for one FRED release. |
+
+**Sources**
+
+| Command | FRED data |
+| --- | --- |
+| `sources` | List all FRED data sources. |
+| `source` | Show metadata for one FRED source. |
+| `source-releases` | List releases published by one FRED source. |
+
+**GeoFRED / Maps (`geofred` subcommands)**
+
+| Command | FRED data |
+| --- | --- |
+| `geofred series-group` | Show GeoFRED series-group metadata (region type, season, frequency, units). |
+| `geofred series-data` | Fetch the regional time series for one FRED series. |
+| `geofred regional-data` | Fetch a regional snapshot — all regions for a single date. |
+| `geofred shapes` | Download a GeoJSON shape file for a region type, to `--out`. |
+
+The GeoFRED endpoints use a different base URL and return regional data keyed by
+FIPS code. `geofred shapes` returns Highcharts-format GeoJSON whose coordinates
+are in a Lambert Conformal Conic projection (not WGS84); reproject before mixing
+with lat/lon basemaps. See `fredq geofred --help` for the full subcommand list.
+
+Each endpoint has its own adaptive help:
+
+```powershell
+uv run fredq series --help
+uv run fredq series-observations --help
+uv run fredq series-search --help
+uv run fredq releases-dates --help
+```
+
+Endpoint help is the primary documentation surface. It shows the FRED target
+endpoint, accepted parameters, allowed value sets, defaults, and examples.
+
+## Dates, Booleans, and Tag Lists
+
+Date parameters accept:
+
+- `YYYY-MM-DD` calendar dates.
+- ISO 8601 datetimes (the time component is dropped; UTC assumed for naive
+  values).
+- Unix timestamps in seconds (≥10 digits).
+
+Boolean parameters accept common true and false forms such as `true`, `false`,
+`1`, `0`, `yes`, and `no`.
+
+Tag lists (`--tag-names`, `--exclude-tag-names`) use semicolons as
+separators, matching FRED's wire format:
+
+```powershell
+uv run fredq tags-series --tag-names "usa;annual"
+```
+
+## ALFRED Point-in-Time
+
+Most endpoints accept `--realtime-start` and `--realtime-end` to view data
+as of a historical date (the [ALFRED](https://alfred.stlouisfed.org/)
+archival API). Combined with `series-vintagedates`, this lets you replay
+what an analyst would have seen on a specific past date — useful for
+backtests and for distinguishing data revisions from real-time signals.
+
+```powershell
+# When were GNP revisions published?
+uv run fredq series-vintagedates --series-id GNPCA
+
+# What did GNP look like on 2024-09-25?
+uv run fredq series-observations --series-id GNPCA \
+  --realtime-start 2024-09-25 --realtime-end 2024-09-25
+```
+
+## Output Contract
+
+fredq writes the FRED response body to stdout exactly as returned. This makes
+it easy to pipe into tools that expect JSON:
+
+```powershell
+uv run fredq series --series-id GNPCA | jq .
+uv run fredq releases --limit 25 | jq '.releases[].name'
+```
+
+Diagnostics, warnings, and errors are written to stderr. The exit code is
+`0` on success, `1` on a FRED request failure, and `2` on a usage or
+configuration error.
+
+## Development
+
+Install development dependencies:
+
+```powershell
+uv sync --all-groups
+```
+
+Run the test suite:
+
+```powershell
+uv run pytest
+```
+
+Run checks locally:
+
+```powershell
+uv run black --check .
+uv run ruff format --check --diff .
+uv run ruff check .
+uv run pyright
+uv run pytest -n auto
+```
+
+Run the full project check, including Python checks across supported
+versions and spelling:
+
+```powershell
+uv run tox
+```
+
+When adding or changing command metadata, update validation, adaptive help,
+and tests together. Then verify the relevant command against FRED with its
+help, minimal required parameters, and representative optional parameters.
+
+## License
+
+fredq is released under the MIT License. See [LICENSE](LICENSE).